caglue - Coding Agent Glue

AI coding agent that works with any OpenAI-compatible API

Why caglue?

Most AI coding tools force you into a specific cloud, a specific model, or a bloated runtime. caglue is different:

• Any API, no lock-in — Works with OpenRouter (default), OpenAI, opencode zen, Gemini, NVIDIA NIM, Together AI, Ollama, LM Studio, llama.cpp, Groq, Cerebras, Cohere, and all OpenAI-compatible backends
• Single static binary — Pure C11, no Python or Node.js runtime needed. One small static binary, runs anywhere.
• 206 built-in tools — File editing, bash, web search, git, SVN, MCP, LSP, subagents, memory, and more in one CLI
• Privacy-first — Use local LLMs via --no-tls --api-base http://localhost:11434/v1
• Subagents (multi-agent) — Delegate focused subtasks to isolated AI agents with their own tools, models, and depth limits
• Provider management — Switch between multiple AI providers with a single command, each with its own credentials and model

What is caglue?

caglue (Coding Agent Glue) is a terminal-based AI assistant that lives in your command line. You type a task in plain English, and it uses AI models — running locally on your machine or in the cloud — to carry it out by reading, writing, and searching your files, running shell commands, browsing the web, managing git repositories, and more.

Think of it as an AI pair programmer that you control through your terminal. It works with any OpenAI-compatible backend, so you are never locked into a single provider.

Core Capabilities

caglue is a full MCP client — discover and invoke tools from any MCP server (stdio subprocess or remote HTTP). Built-in tools wrap the MCP protocol so the AI can call external tools seamlessly.

Config file: ~/.config/caglue/mcp.json — supports both stdio subprocess and remote HTTP transports.

Subagents (Multi-Agent)

Delegate focused subtasks to isolated AI agents. Each subagent gets its own context and tool set, may run a different model, and runs in parallel or sequence before reporting results back to the parent.

Subagents inherit parent's permission mode and hooks. Use tool_task_run, tool_task_run_batch, tool_task_run_chain from tools, or /agent-run <name> "<prompt>" to run a file-based agent definition. Agent files live in ~/.config/caglue/agents/*.md and may carry tools_whitelist, max_rounds, and depth_limit; a run is refused when the parent depth plus the agent's depth_limit would exceed 3. Manage transcripts with /subagent-list, /subagent-resume, /subagent-purge.

Language Server Protocol (LSP)

Native LSP client built in — 14 LSP tools for code intelligence: diagnostics, workspace diagnostics, hover, definition, references, implementation, type definition, rename, document symbols, workspace symbols, call hierarchy, code actions, and formatting. Works with any LSP server (clangd, gopls, rust-analyzer, pyright, typescript-language-server, etc.).

There is no caglue lsp CLI subcommand — LSP is exposed as lsp_* tools that the model invokes from the REPL. Disable specific servers via config lsp_disable (CSV of server IDs).

Subversion (SVN) Support

Full SVN tooling alongside git — 12 SVN tools: diff, status, log, info, add, revert, delete, commit, update, move, cleanup, copy. Useful for legacy codebases or mixed VCS environments.

There is no caglue svn CLI subcommand — SVN is exposed as svn_* tools that the model invokes from the REPL.

PDF Converter

Convert PDFs to Markdown, JSON, HTML, or semantic chunks. Four modes: text_only (fast text extraction), structure (heuristic layout), ocr (VLM-based OCR), vlm (advanced VLM analysis). Supports encrypted PDFs (Standard Security Handler Rev 2–6).

DNS Tools (dig/nslookup Parity)

BIND9-compatible dig and nslookup subcommands: UDP/TCP, EDNS0 (+edns/+do/+bufsize=N), DoT (DNS over TLS), DoH (DNS over HTTPS, +https=URL), AXFR/IXFR zone transfer, +trace iterative resolver, section toggles (+[no]answer, +[no]authority, +[no]additional), +identify, +short, +multiline, reverse lookup via -x.

GNU Parallel Parity

caglue parallel — GNU parallel-compatible core. Supports -N, -L, -j, --colsep, --pipe, --halt, {}/{.}/{/} replacements, -C attached values (-C,), plus --results, --joblog, --timeout, --retries, --bar, --eta.

Visual Canvas (48 tools)

The largest single tool family in caglue. A programmatic scene graph for diagrams, mockups, and schematics — no GUI toolkit, no browser engine. The model states the structure and caglue lays it out.

• Diagram composition — canvas_flowchart, canvas_sequence, canvas_tree, canvas_mindmap, canvas_er, canvas_network, canvas_grid, canvas_table (all with automatic layout)
• Shape primitives — canvas_add (rect / ellipse / line / polygon / path / regular polygon) and canvas_shape_add for theme stencils
• Layers — canvas_layer_add, _reorder, _merge, _flatten, _solo, plus per-layer opacity / blend / visibility / lock
• Connector routing — canvas_connector_add / _edit / _route with auto-port and orthogonal routing
• Layout polish — canvas_align, canvas_distribute, canvas_snap, canvas_resolve_overlaps, canvas_zorder
• Inspection — canvas_describe, canvas_dump, canvas_diff, canvas_query, canvas_validate (WCAG contrast), canvas_overlap_report, canvas_style_check, canvas_palette

Git & SVN Working Copy Management

Full read/write coverage of both major version control systems, plus managed worktrees for isolated parallel work.

• Git (19 tools) — git_diff, git_log, git_show, git_status, git_blame, git_branch, git_tag, git_stash, git_remote, git_add, git_commit, git_checkout, git_reset, git_merge, git_fetch, git_push
• Managed worktrees — git_worktree_add creates a detached worktree under .git/caglue-worktrees/ so an agent can edit in isolation; git_worktree_list and git_worktree_remove manage the set
• SVN (12 tools) — svn_info, svn_status, svn_log, svn_diff, svn_add, svn_update, svn_commit, svn_revert, svn_delete, svn_move, svn_copy, svn_cleanup (lock recovery)

Local RAG Store

An embedded vector store over your own files — no external service. Index a directory, a single file, or the commit history of a local git repository, then retrieve relevant chunks into the AI's context.

• Ingest — caglue rag add <path|url> indexes a file or directory; --git <repo> indexes commit history (one document per commit); --command CMD indexes a subprocess' stdout. HTML is normalized, raw bytes preserved, duplicate content skipped by sha256.
• Query — caglue rag search <query> with --top-k, --threshold, --filter-json (source / mtime_from / mtime_to / meta), and --extra-query for multi-query merge (capped at 8). caglue rag ask answers directly with [n] citations.
• Maintain — list, stats, remove <id>, reindex, expire (TTL sweep), config, setup (interactive editor)
• Portability — export <file> / import <file> move a whole store as portable JSON (id / text / metadata / embeddings); re-embedding happens only on dimension mismatch
• Stay in sync — caglue rag watch <dir> [--pattern PAT] keeps the store current as files change (Ctrl-C to stop)
• Expose — caglue rag serve runs an MCP stdio server over the RAG tools; mutation tools are gated by .caglue/rag-mcp.json, fail-closed by default

Checksums & Digests

A complete coreutils-compatible checksum family built in pure C — 10 subcommands, no coreutils dependency, no subprocess spawn.

• Family 1 (GNU format) — sum, cksum, hashsum, md5sum, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, b2sum — output byte-compatible with the GNU tools, so existing checksum files verify.
• Verify mode — -c reads a previously written checksum file and reports mismatches

Embedded Test Suite & Session Replay

The test suite is compiled into the executable — no test runner to install, no make check prerequisite. Every test is forked into its own child process, so a crash in one test cannot take the suite down and ports/temp files never collide. 270 tests registered, run in parallel.

• Test kinds — each test is tagged with a dependency level so offline runs stay clean: PURE (220, no external dependencies), NETWORK (27, loopback mock servers only), INTEGRATION (17, multi-module), EXTERNAL (6, require third-party binaries).
• TAP output — standard ok N / not ok N / 1..N, so any TAP consumer can read it. AddressSanitizer runs are gated by make check-asan.
• Session replay — caglue replay <session-id> prints a session's rollout JSONL to stdout, so a past conversation can be piped into jq, diff, or a file for offline inspection.

Crypto (PEM & Big Number)

Pure C11 cryptographic primitives — no OpenSSL dependency at all (the TLS backend is entirely self-implemented pure C). These ship as libraries (libcaglue_pem, libcaglue_bignum), not CLI subcommands: PEM (RFC 7468 encode/decode) and Big Number arithmetic (Karatsuba multiplication, Knuth division, Miller-Rabin primality, modpow, modinv, GCD). Foundation for RSA, X.509, AES, and the TLS 1.2/1.3 implementation.

✅ Linux x86_64 — ready (static binary)
✅ Linux aarch64 — ready (static binary)
✅ macOS 12+ (Apple Silicon) — ready
✅ No Python or Node.js required.

Download

All releases

macOS: if Gatekeeper blocks the unsigned binary, run xattr -d com.apple.quarantine caglue to remove the quarantine attribute.

Setup

caglue setup walks you through an interactive wizard: pick a provider preset, enter credentials, choose a model, and configure global behavior (permission mode, gate timeouts, hooks). Your settings are saved in ~/.config/caglue/config.

Or set the environment variable directly:

Quick one-liner shortcuts

Once configured, these CLI shortcuts let you inspect or switch settings on the fly:

Quick example

Here is what a real caglue session looks like. The user just types what they want in plain English, and caglue takes care of the rest:

How it works

1. You describe the task — say "explain this function" or "fix the bug in main.c"
2. caglue plans and acts — it reads your code, runs commands, searches the web, edits files, all on its own
3. You review every change — each file edit is shown as a diff; you approve or reject before anything is written
4. Optional review round — caglue can run an AI security/quality review on its own changes before handing control back

Usage

1. Check your installation

2. Start the interactive REPL

Run caglue with no arguments to start an interactive session. You are talking to an AI — just describe what you need in plain language.

Inside the REPL, these slash commands help you control the session:

caglue also loads ./.caglue/instructions/*.md automatically when the directory exists — commit these to your repository so every contributor (and AI) follows the same conventions. A user-global scope at ~/.config/caglue/instructions/*.md applies across all projects as well. Run caglue init to scaffold the project-local directory. Files load in lexicographic order; use 00-, 10- prefixes to control ordering.

💡 Prompt marks (OSC 133): caglue wraps every prompt in FinalTerm semantic markers — press Ctrl+Shift+↑/↓ in iTerm2, WezTerm, Kitty, or Windows Terminal to jump between turns.

REPL key bindings

3. One-shot mode (no REPL)

Pass a task and file directly — caglue runs once and exits. Great for scripting or quick questions.

4. Use a local LLM

Point caglue at Ollama, vLLM, or any OpenAI-compatible server running on your machine. No data leaves your computer.

5. Set environment variables

Skip typing --api-base and --api-key every time by exporting these in your shell profile:

6. Non-interactive / auto-approve

When you trust caglue and want to skip confirmation prompts (e.g. in CI), pass --auto-approve to auto-approve every action, or export CAGLUE_YES=1 for the same effect via the environment. The persistent equivalent is the permission_mode config key — caglue config set permission_mode bypass — one of five modes (deny / ask / allow / bypass / plan).

Skills & Automation

caglue ships with built-in skills — ready-to-use workflows that combine instructions and tool access patterns for common tasks. Use them from the REPL (/skill review) or the CLI:

• init — Scaffold ./.caglue/instructions/ for a new project (caglue init)
• review — Thorough review of uncommitted or staged changes, ordered by severity
• security-review — Security-focused review of pending changes before committing
• commit — Draft and run a git commit with a well-formed message based on staged changes

Subagents (Multi-Agent Workflows)

Delegate focused subtasks to isolated conversation contexts. Each subagent runs with its own tool whitelist, model override, and depth limit — perfect for parallel security reviews, code analysis, or test generation.

Agent files live in ~/.config/caglue/agents/*.md and ./.caglue/agents/*.md — define tools_whitelist, model_override, max_rounds, depth_limit, and custom system prompts per agent. Depth is capped at 3: a subagent is refused when its own depth_limit plus the parent's depth would exceed that.

Session management

Save, fork, and restore entire REPL sessions. Each session preserves conversation history, context budget state, and provider settings.

What can you do with caglue?

• Understand unfamiliar code — paste a file and ask "explain what this does", or generate a full repository map
• Fix bugs and refactor — describe the problem and let caglue find and edit the right files; review every change before it is applied
• Search and browse — search your codebase with regex, fetch web pages, or ask it to research a topic online
• Manage git workflows — diff, commit, push, merge, stash, blame — all through natural language
• Run tests and builds — type "build and run tests" and see the results without switching contexts
• Work with local LLMs — connect to Ollama / vLLM / llama.cpp on your own machine, no data ever leaves
• Orchestrate subagents — delegate parallel subtasks (security review, test generation) to isolated AI agents with custom tools and models
• Extend via MCP — plug in external tool servers (databases, cloud APIs, browser automation) using the Model Context Protocol

Quick Start — Usage

Get productive in minutes:

1. Install — Download the static binary for your platform (see Download)
2. Configure — Run caglue setup to pick a provider (opencode zen, OpenAI, Ollama, etc.) and enter credentials
3. Start coding — Run caglue for the interactive REPL, or use one-shot: caglue -p "explain this function" -f parser.c

Tools at a glance

caglue ships with 206 built-in tools organized by category. Every tool declares a JSON Schema for its parameters, so the AI knows exactly what each one expects.

📁 File I/O — read_file, write_file, edit_file, multi_edit, edit_files, apply_context_patch, apply_unified_diff, delete_file, move_file, copy_file, mkdir, chmod, symlink
📂 File Discovery — glob, list_dir, tree, find, search_files, file_stat, file_hash, file_meta, resolve_path, repository_map, watch_files, which
📦 Archive — archive_extract, archive_create, archive_list (zip/tar/tgz/tbz2/txz/tzst/7z)
🔍 Diff — diff_files, diff_dirs
🌐 Web — web_fetch, web_save, web_search, wget
⚡ Process — bash, shell, node, python3, awk, parallel, process_list, process_output, process_kill, process_input, process_wait, process_status
🧩 JSON & YAML — json_extract, json_patch, json_validate, yaml_to_json, yaml_validate
✏️ Text & Data — text_transform, regex_test, regex_replace, calculate, string_hash, crc_string, hex_dump, random_bytes, uuid_v4, wc
🔨 Build & Test — build, run_tests, caglue_subcmd, caglue_subcmd_mut
🧠 Agent Meta — ask_user_question, notify_user, todo_write, memory_read, memory_write, memory_delete, memory_search, rag_add, rag_search, rag_remove, rag_list, rag_config, rag_reindex, read_env, list_tools, tool_info, session_status, context_compact, attach_file
🗃️ Git — git_diff, git_status, git_log, git_show, git_add, git_commit, git_checkout, git_branch, git_push, git_merge, git_reset, git_stash, git_fetch, git_blame, git_tag, git_remote, git_worktree_list, git_worktree_add, git_worktree_remove
🗃️ SVN — svn_diff, svn_status, svn_log, svn_info, svn_add, svn_revert, svn_delete, svn_commit, svn_update, svn_move, svn_cleanup, svn_copy
🎨 Visual Canvas — 48 tools for diagrams: canvas_create, canvas_flowchart, canvas_sequence, canvas_er, canvas_tree, canvas_mindmap, canvas_network, canvas_grid, canvas_table, canvas_shape_add, canvas_shape_custom, canvas_stencil_list, canvas_text_add, canvas_add, canvas_connector_add, canvas_connector_edit, canvas_connector_route, canvas_group, canvas_ungroup, canvas_load, canvas_save, canvas_zorder, canvas_align, canvas_distribute, canvas_snap, canvas_layer_add, canvas_layer_remove, canvas_layer_reorder, canvas_layer_list, canvas_layer_merge, canvas_layer_flatten, canvas_layer_set_visible, canvas_layer_solo, canvas_layer_set_opacity, canvas_layer_set_locked, canvas_layer_set_blend, canvas_obj_edit, canvas_obj_delete, canvas_describe, canvas_query, canvas_dump, canvas_diff, canvas_validate, canvas_style_check, canvas_palette, canvas_overlap_report, canvas_resolve_overlaps, canvas_destroy
📄 PDF — pdf_read, pdf_convert, pdf_info, pdf_metadata, pdf_fonts, pdf_create, pdf_embed_image, pdf_image_extract, pdf_rasterize, pdf_merge, pdf_separate, pdf_detach
🖼️ Media — image_generate, image_convert, image_analyze, audio_speak, video_generate
🤖 Subagents — tool_task_run, tool_task_run_batch, tool_task_run_chain, agent_shared_memory_set, agent_shared_memory_get, agent_broadcast, agent_barrier, agent_reduce
🔍 LSP — 14 clangd-powered tools: lsp_definition, lsp_references, lsp_hover, lsp_type_definition, lsp_implementation, lsp_document_symbols, lsp_workspace_symbol, lsp_workspace_diagnostics, lsp_diagnostics, lsp_code_actions, lsp_apply_code_action, lsp_rename, lsp_format, lsp_call_hierarchy (auto-registered when clangd is available)
🔌 MCP — Model Context Protocol server integration (risk-classified tools, available to the AI as <server>:<tool>)
🕐 System — now, sysinfo
📜 Large tool results — read_tool_result, search_tool_result (page through or grep a tool output that exceeded the context window)

Full tool list: run caglue tools or call the list_tools tool from the REPL.

Update

Provider Management

Switch between multiple AI providers (opencode zen, OpenAI, Ollama, Groq, OpenRouter, etc.) with a single command. Each provider has its own API endpoint, credentials, and default model — caglue resolves the active one at request time.

Default endpoint: OpenRouter (https://openrouter.ai/api/v1, model openrouter/auto). Use /models in the REPL to list other model IDs offered by the active endpoint.

Configuration

caglue reads settings from ~/.config/caglue/config (INI-style). Run caglue setup to create one interactively, or edit the file directly for fine-grained control. Provider-specific settings live in [provider <name>] sections; global behavior settings are in the auto-block.

Priority (highest first): CLI flags > environment variables > config file > built-in defaults

Provider configuration (per-provider)

• api_base — API endpoint URL
• api_key — Your API key (also via OPENAI_API_KEY)
• model — Default model name

Global configuration (caglue behavior)

• permission_mode — ask | allow | deny | bypass | plan (default: ask)
• max_rounds — Maximum AI action steps per turn (default 100)
• auto_approve — Skip all permission prompts (use with care)
• timeout_ms — HTTP request timeout (default 3600000)
• gate_ro_timeout_ms — Auto-select timeout for read-only tools (default 8000)
• gate_timeout_ms — Auto-select timeout for general tools (default 0 = disabled)
• verify_command — Auto-run after every tool round (e.g. make check)
• hook_pre_tool_use / hook_post_tool_use — Run scripts before/after tool dispatch
• hook_session_start / hook_session_end — Run scripts at session boundaries
• instructions — Single-line additional system prompt
• project_instructions — Load ./.caglue/instructions (default true)
• map_tokens — Token budget for repository_map (0 = default 4000)
• lsp_disable — CSV of built-in LSP server ids to disable
• sandbox — Bash subprocess sandbox policy: auto | on | off (Linux: bwrap, macOS: sandbox-exec)
• tool_prompt_compat — Stronger tool-call prompt for non-OpenAI models (default off)
• no_color — Disable ANSI colour (any value)
• mouse — Enable mouse support in REPL
• compact_threshold — Token budget % to trigger proactive compaction (0 = scale-adaptive default; explicit range 1-99)
• review_prompt — Custom system prompt for the review round
• parallel — Default parallelism for caglue parallel (0 = unlimited, default ncpu)
• no_tls — Disable TLS for API connections
• insecure — Skip TLS certificate verification
• provider — Active provider preset name
• tool_schema_mode — Tool schema flavour sent to the model
• media_output_dir — Directory for generated images / audio
• media_image_model / media_tts_model / media_tts_voice — Media generation models

RAG store configuration (caglue rag)

• rag.enabled — Enable the local vector store
• rag.model / rag.provider — Embedding model and backend
• rag.store_path / rag.originals_dir — Store and source-original locations
• rag.top_k / rag.threshold — Retrieval depth and similarity cutoff
• rag.namespace / rag.memory_index / rag.watch_patterns / rag.ttl_hours / rag.query_rewrite — Namespacing, auto-indexing, refresh and query behaviour

Full list (77 keys): run caglue config keys.

Permission modes

caglue has five permission modes (ask / allow / deny / bypass / plan) that control what the AI can do. Switch between the three cycling modes with Shift+Tab inside the REPL:

• PLAN — Read-only. The AI can inspect files and search but never modify anything. Safe for exploration.
• ASK — Every write or destructive action waits for your approval (y/s/a/n). Default.
• BYPASS — Full trust. All actions proceed without confirmation. Use only when you fully trust the model.

Model Context Protocol (MCP)

Extend caglue with external tool servers using the MCP standard. Connect to databases, cloud services, or custom toolchains — caglue automatically classifies each MCP tool by risk level and applies permission rules per server.

Verbs: list, tools <server>, presets, add <preset> [name], remove <name>, env, include, exclude. Changes take effect on next launch; inside the REPL use /mcp refresh.

Or add servers to ~/.config/caglue/mcp.json — supports stdio subprocess, remote Streamable HTTP, environment variables, and per-server tool include/exclude filters:

Browser mirror (webmirror)

Mirror your REPL session to a browser in real time — useful for demos, pairing, or monitoring from another device on the same LAN. The browser shows a full terminal emulator with ANSI color, CJK support, keyboard input, and a scrollback buffer.

⚠️ The browser view is session-equivalent — it can run commands, edit files, and answer permission gates. HTTP Basic Auth is the only protection. Set credentials via environment variables (CAGLUE_WEB_USER, CAGLUE_WEB_PASS, CAGLUE_WEB_PASS_ENV) or type them at the interactive prompt.

While active, the footer shows a web chip with the current viewer count (real-time across LAN). Use /stop-web to shut it down when no longer needed.

Static web server (caglue serve)

Run a standalone HTTP/1.1 static-file server with FastCGI proxy and WebSocket support. Useful for local development, demos, or serving documentation. Binds 127.0.0.1 by default — pass --bind 0.0.0.0 to expose deliberately.

Token usage tracking

Track token consumption per model and per day from local rollout logs. No API connection required — caglue reads ~/.local/share/caglue/rollout/*.jsonl.

Set CAGLUE_PRICE_<MODEL>_IN/_OUT/_CACHED (per-1M tokens) to add a USD column.

Debug mode

When something does not work as expected, run with --verbose (or -v) to see detailed logs of every HTTP request, tool dispatch, and AI response. Repeat for more verbosity (-vv).