caglue - Coding Agent Glue

AI coding agent that works with any OpenAI-compatible API

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 (or Korean), 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.

Why caglue?

• 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
• ~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

✅ Linux x86_64 — ready (static binary)
✅ Linux aarch64 — ready (static binary)
✅ macOS 12+ (Apple Silicon / Intel) — 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 --yes to auto-approve every action.

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, and custom system prompts per agent.

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

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

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: 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 120000)
• 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

CLI commands: caglue config list, caglue config get <key>, caglue config set <key> <value>, caglue config unset <key>.

Advanced

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.

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 support. Useful for local development, demos, or serving documentation.

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