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 opencode zen (default), OpenAI, Ollama, vLLM, LiteLLM, Groq, OpenRouter, and all OpenAI-compatible backends
Single static binary — Pure C11, no Python or Node.js runtime needed. ~4MB download, runs anywhere.
~100 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.

caglue mcp list

→ List configured MCP servers

caglue mcp add myserver --command "npx -y @modelcontextprotocol/server-filesystem" --args "/tmp"

→ Add stdio MCP server

caglue mcp add remote --url https://api.example.com/mcp --header "Authorization: Bearer ..."

→ Add remote HTTP MCP server

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 has its own tool set, model, context window, and depth limit (default max depth 3). Subagents run in parallel or sequence and report results back to the parent.

/subagent "review security of auth module" --tools read_file,search_files --model gpt-4o --max-depth 2

→ Launch a focused subagent

Subagents inherit parent's permission mode and hooks. Use tool_task_run, tool_task_run_batch, tool_task_run_chain from tools.

Language Server Protocol (LSP)

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

caglue lsp start -- clangd

→ Start LSP server (clangd example)

caglue lsp diagnostics -f src/main.c

→ Get diagnostics for a file

Disable specific servers via config lsp_disable (CSV of server IDs).

Subversion (SVN) Support

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

caglue svn status

→ SVN working copy status

caglue svn diff -r HEAD

→ SVN diff against HEAD

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).

caglue pdfconvert paper.pdf --format markdown --mode structure

→ Convert with layout analysis

caglue pdfconvert encrypted.pdf --password "secret" --format json

→ Decrypt and convert

DNS Tools (dig/nslookup Parity)

BIND9-compatible dig and nslookup subcommands with 100% feature parity: UDP/TCP, EDNS0, DoT (DNS over TLS), DoH (DNS over HTTPS), AXFR/IXFR zone transfer, +trace iterative resolver, +nssearch, reverse lookup.

caglue dig example.com +trace +dnssec

→ Iterative trace with DNSSEC

caglue dig @1.1.1.1 example.com +tls +tlsverify

→ DNS over TLS with cert verification

caglue nslookup -port=853 -type=MX example.com

→ nslookup on DoT port

GNU Parallel Parity

caglue parallel — drop-in replacement for GNU parallel. Supports -N, -L, -j, --colsep, --pipe, --halt, {}/{.}/{/} replacements, -C attached values (-C,), exit code = failed job count (capped at 101).

caglue parallel -j4 -N2 echo job {1} {2} ::: a b c d e f

→ Run jobs in parallel (2 args per job)

printf 'a,1\nb,2' | caglue parallel -C, echo col1={1} col2={2}

→ CSV column splitting

Crypto (PEM & Big Number)

Pure C11 cryptographic primitives — no OpenSSL dependency for core operations: PEM (RFC 7468 encode/decode), Big Number arithmetic (Karatsuba multiplication, Knuth division, Miller-Rabin primality, modpow, modinv, GCD). Foundation for RSA, X.509, TLS 1.2/1.3 implementation (Phase T4/T5 complete).

caglue pem decode -i key.pem -o key.der

→ PEM to DER

caglue bignum modpow --base 2 --exp 100 --mod 97

→ Modular exponentiation

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

Download

curl \
  https://www.minzkn.com/public/release/caglue/caglue-latest-linux-x86_64 \
  -o caglue

→ Linux x86_64

curl \
  https://www.minzkn.com/public/release/caglue/caglue-latest-linux-aarch64 \
  -o caglue

→ Linux aarch64

curl \
  https://www.minzkn.com/public/release/caglue/caglue-latest-darwin-aarch64 \
  -o caglue

→ macOS Apple Silicon

curl \
  https://www.minzkn.com/public/release/caglue/caglue-latest-darwin-x86_64 \
  -o caglue

→ macOS Intel

chmod +x caglue

→ Make executable (all platforms)

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.

caglue setup

→ Configure API key, model, preferences

Or set the environment variable directly:

export OPENAI_API_KEY="sk-..."

→ Use default provider (opencode zen)

Quick one-liner shortcuts

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

caglue model

→ Show current model

caglue model gpt-4o

→ Switch model

caglue api-base http://localhost:11434/v1

→ Point to a different endpoint

caglue doctor

→ End-to-end health check

caglue usage

→ Token consumption (last 30 days)

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:

$ caglue

→ Start the interactive REPL

You: explain src/parser.c in 3 sentences

→ caglue reads the file and summarises it

You: add a null-check before the memcpy call

→ caglue finds the code, edits it, and shows you the diff

You: run the tests to make sure nothing broke

→ caglue runs make check and reports pass/fail

How it works

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

Usage

1. Check your installation

caglue --help

→ See all flags and subcommands

caglue --version

→ Print version and build info

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.

caglue

→ Start interactive REPL

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

/help

→ List available slash commands

/compact

→ Summarise conversation to save context

/instructions ...

→ Set custom system prompt for the session

/plan "explore the codebase structure"

→ Side-effect-free planning turn (read-only)

/review

→ Toggle review mode or run one-shot review

/doctor api

→ Diagnose API/provider connectivity

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

`Tab`	Complete slash command or filename
`Shift`+`Tab`	Cycle permission mode (PLAN → ASK → BYPASS)
`Alt`+`Enter`	Insert literal newline (multiline composer)
`Ctrl`+`O`	Open last response in `$PAGER`
`Ctrl`+`R`	Reverse-search history
`↑`/`↓`	Previous/next visual row or history entry
`Ctrl`+`A`/`E`	Beginning / end of line
`Ctrl`+`K`/`U`	Kill to end / beginning of line
`Ctrl`+`W`	Kill previous word
`Ctrl`+`Y`	Yank (paste)
`Ctrl`+`L`	Clear screen
`Ctrl`+`C`	Cancel current turn; press twice within 2s to exit

3. One-shot mode (no REPL)

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

caglue "explain this function" -f parser.c

→ Explain a specific file

caglue "find potential bugs" -f src/

→ Review a directory

caglue "add error handling to main" -f main.c

→ Ask caglue to edit your code

4. Use a local LLM

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

caglue --no-tls --api-base http://localhost:11434/v1 \
  --model llama3

→ Ollama on localhost

5. Set environment variables

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

export OPENAI_API_KEY="sk-..."

→ Your API key

export OPENAI_API_BASE="https://api.openai.com/v1"

→ API base URL

export OPENAI_MODEL="gpt-4o"

→ Default model name

6. Non-interactive / auto-approve

When you trust caglue and want to skip confirmation prompts (e.g. in CI), pass --yes to auto-approve every action.

caglue --yes "fix all lint warnings" -f src/

→ Auto-approve mode

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-run review "Check for SQL injection vulnerabilities"

→ Run a file-based subagent with custom prompt

caglue agent list

→ List available agent definitions

Agent files live in ~/.config/caglue/agents/*.md and ./.caglue/agents/*.md — define tools_whitelist, model_override, max_rounds, and custom system prompts per agent.

caglue skill run review

→ Run the review skill (or /skill review inside the REPL)

Session management

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

/session mysession

→ Save or load a named session

/sessions

→ List all saved sessions

/fork experiment

→ Fork current session into a new id

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:

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

Tools at a glance

caglue ships with ~100 built-in tools organized by category. Every tool has an --api-base-agnostic JSON schema, so the AI knows exactly what parameters each one expects.

📁 File I/O — read_file, write_file, edit_file, multi_edit, apply_context_patch, apply_unified_diff, delete_file, move_file, copy_file, mkdir, chmod, symlink
📂 File Discovery — glob, list_dir, tree, search_files, file_stat, file_hash, resolve_path, file_meta, repository_map
📦 Archive — archive_extract, archive_create, archive_list (zip/tar/tgz/tbz2/txz)
🔍 Diff — diff_files, diff_dirs
🌐 Web — web_fetch, web_save, web_search
⚡ Process — bash, 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 & Crypto — text_transform, regex_test, string_hash, random_bytes, uuid_v4
🔨 Build & Test — build, run_tests
🧠 Agent Meta — ask_user_question, notify_user, todo_write, memory_read, memory_write, memory_delete, memory_search, read_env, list_tools, tool_info, session_status, repository_map, 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
🗃️ 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
🔌 MCP — Model Context Protocol server integration (risk-classified tools)
🔍 LSP — clangd-powered code intelligence (lsp_*, auto-registered when clangd is available)

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

Update

caglue update

→ Check and install latest version

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.

caglue provider list

→ List registered providers (active marked with *)

caglue provider presets

→ Show built-in preset catalogue

caglue provider add

→ Interactive wizard: pick preset → credentials → model

caglue provider add --preset openai

→ Non-interactive: use preset defaults

caglue provider edit openai

→ Re-prompt with current values as defaults

caglue provider use ollama

→ Switch active provider (persists)

caglue provider test openai --with-chat

→ Probe /v1/models + 1-token chat completion

caglue provider remove oldprovider

→ Delete a provider section

Default endpoint: opencode zen (https://opencode.ai/zen/v1, model big-pickle). 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 600000)
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 (default 75%)
review_prompt — Custom system prompt for the review round
dns_servers — CSV of DNS servers for dig/nslookup (overrides resolv.conf)
dns_timeout — DNS query timeout in ms (default 5000)
dns_retries — DNS retry count (default 2)
parallel_jobs — Default parallelism for caglue parallel (default: ncpu)
parallel_colsep — Default column separator regex for caglue parallel
ssh_known_hosts — Path to known_hosts for SSH git remotes
git_worktree — Enable git worktree support (default true)

Full list: run caglue config list or see caglue --help.