README
¶
codag CLI
Codag compresses noisy log streams into compact incident capsules for AI agents. It is built for the moment when raw distributed-systems logs are too large to fit in context, too expensive to ship directly to a model, or too slow for an agent to reason over line by line.
The CLI can be used directly from a terminal or registered as an MCP server for agents such as Claude Code, Codex, and Cursor.
Install
From source:
git clone https://github.com/codag-megalith/codag-cli.git
cd codag-cli
make build
make install
With Go:
go install github.com/codag-megalith/codag-cli@latest
Setup
codag setup
codag whoami
codag setup signs you in through the browser, registers the Codag MCP server
with supported agents, and can optionally pre-warm your template cache from
detected log sources.
Authentication uses Codag's OAuth device flow. Tokens are stored in
~/.config/codag/config.json with file mode 0600.
Core Commands
| Command | Use |
|---|---|
codag wrap -- <cmd> |
Run any log command and return a compact summary. |
codag wrap --mode capsule -- <cmd> |
Return the structured JSON incident capsule. |
codag wrap --mode parse -- <cmd> |
Return the templated parse output. |
codag onboard |
Pre-warm the template cache from recent historical logs. |
codag mcp serve |
Run the MCP server used by agents after codag setup. |
codag disable |
Remove Codag MCP tools from known agent configs. |
codag auth login |
Sign in with the browser device-flow login. |
codag auth refresh |
Refresh the saved OAuth session. |
codag auth logout |
Remove saved OAuth tokens. |
| `codag config <set | get |
codag help-llm |
Print an agent-pasteable usage guide. |
codag version |
Print the CLI version. |
Examples
The agent-friendly pattern:
codag wrap -- vercel logs --since=1h
codag wrap -- railway logs --service worker
codag wrap -- aws logs tail /aws/lambda/my-fn --since=30m
codag wrap -- kubectl logs my-pod -n prod --tail=2000
Pipe an existing stream:
vercel logs --since=1h | codag wrap
cat /var/log/app.log | codag wrap --service api
Use a different API or console host:
CODAG_SERVER=http://localhost:8765 codag wrap -- cat app.log
CODAG_CONSOLE=http://localhost:3000 codag auth login
MCP
After codag setup, supported agents can call Codag tools directly instead of
fetching raw logs through shell commands. For example, an agent can call
tail_kubernetes, tail_aws_logs, or the generic wrap tool and receive a
compact capsule instead of thousands of raw log lines.
If your Codag org runs out of credits or needs a billing action, MCP tool errors
include a stable marker such as CODAG_CREDITS_EXHAUSTED and tell the agent to
send you to billing or run codag disable.
Data Handling
Codag sends the log lines you pass to codag wrap, codag onboard, or MCP tools
to the configured Codag API server for compression. Provider credentials used by
local source connectors stay in your local Codag config unless a provider API
request itself requires them.
Use CODAG_SERVER or codag config set server <url> to point the CLI at a
self-hosted, staging, or local API.
Development
make test
make build
./bin/codag --help
The project is intentionally small: a Go CLI, HTTP client, OAuth device-flow auth, MCP server, and provider/source helpers.
Documentation
¶
Overview ¶
codag — token-efficient log compression for coding agents. Wraps log commands like `vercel logs`, `railway logs`, `aws logs`, etc. and replaces noisy raw output with a compact summary the agent can paste into its context.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
api
Package api is a thin HTTP client for the templater server.
|
Package api is a thin HTTP client for the templater server. |
|
auth
Package auth implements the OAuth 2.0 device-code flow that `codag setup` and `codag auth login` use to sign a user in via their browser, plus the single-flight refresh middleware that the api.Client uses to handle expired tokens transparently.
|
Package auth implements the OAuth 2.0 device-code flow that `codag setup` and `codag auth login` use to sign a user in via their browser, plus the single-flight refresh middleware that the api.Client uses to handle expired tokens transparently. |
|
config
Package config loads + persists user-level CLI config.
|
Package config loads + persists user-level CLI config. |
|
exec
Package exec runs child processes and streams their output line-by-line.
|
Package exec runs child processes and streams their output line-by-line. |
|
mcp
Package mcp implements a minimal stdio MCP (Model Context Protocol) server that exposes codag's log-tail tools to any MCP-aware agent — Claude Code, Cursor, Codex, Continue, Cline, etc.
|
Package mcp implements a minimal stdio MCP (Model Context Protocol) server that exposes codag's log-tail tools to any MCP-aware agent — Claude Code, Cursor, Codex, Continue, Cline, etc. |
|
onboard
Package onboard ingests historical logs from external sources and streams them to the codag server's /v1/onboard/warm endpoint to pre-populate the org's template_cache.
|
Package onboard ingests historical logs from external sources and streams them to the codag server's /v1/onboard/warm endpoint to pre-populate the org's template_cache. |
|
onboard/sources
Package sources contains the per-origin log fetchers used by `codag onboard`.
|
Package sources contains the per-origin log fetchers used by `codag onboard`. |
|
setup
Package setup implements `codag setup` — the one-shot installer that gets a developer from "binary on PATH" to "MCP-aware agents pulling codag for log work" with auth wired up.
|
Package setup implements `codag setup` — the one-shot installer that gets a developer from "binary on PATH" to "MCP-aware agents pulling codag for log work" with auth wired up. |