codog

module
v0.0.0-...-dc022f5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 10, 2026 License: MIT

README

Codog

Codog is a Go-native, single-binary coding agent for real terminal work. It keeps the important parts of an agent runtime in one inspectable binary: model streaming, workspace tools, permissions, local sessions, hooks, skills, MCP, and a full-screen terminal UI.

Codog references Claude Code's local product shape and coding workflows, but it does not copy Claude Code's implementation, does not pretend to be an Anthropic product, and does not treat hosted commercial services as part of the local closure target. The goal is a practical Go-native equivalent for local repositories: verified interaction, tool execution, session state, and extension surfaces that can be studied and changed.

Codog is most useful today when you want:

  • a terminal coding agent with local, file-backed state;
  • a Go codebase that shows how agent loops and tool execution fit together;
  • explicit permission checks before model-requested actions affect a workspace;
  • room to experiment with Claude-Code-style workflows without a multi-runtime stack.

It is not a drop-in replacement for commercial hosted services, official IDE extensions, enterprise admin backends, or proprietary account systems.

Quick Start

Codog requires Go 1.26 or newer and at least one model credential.

go install github.com/Rememorio/codog/cmd/codog@latest
export ANTHROPIC_API_KEY=<key>

From a source checkout, install the single binary into ~/.local/bin:

scripts/install.sh

Use scripts/install.sh --bin-dir DIR to install into a specific directory.

Run it from a repository:

codog -p "summarize this project"

For multi-turn work, start Codog from a repository. The default interactive command opens the full-screen TUI; the legacy line-oriented shell remains available as repl.

codog
codog tui
codog repl

Use codog doctor to check local configuration and codog help for the full command reference.

Design Principles

Codog is built around a few constraints.

Local first. Sessions, summaries, usage data, todos, exports, and most runtime state are plain local files rather than hidden service state.

Explicit execution. The model can request tools, but the runtime decides whether they are allowed. Permission mode, workspace boundaries, allow and deny lists, hooks, and policy checks all happen before host actions run.

One binary. The CLI, REPL, TUI, provider client, tool runtime, MCP surfaces, skills, hooks, background jobs, and bridge helpers are implemented in Go and ship as a single command.

Readable internals. The project favors ordinary packages and file-backed data formats over opaque generated state, so the runtime can be debugged with normal tools.

How It Works

A Codog turn follows the same loop whether it starts from a one-shot prompt, REPL, TUI, or bridge call:

  1. Load configuration, project instructions, focused files, and optional session history.
  2. Stream a request to the configured model provider.
  3. Parse assistant text and requested tool calls.
  4. Check permissions, workspace boundaries, allow and deny rules, hooks, and local policy.
  5. Execute approved tools and append the result to the session ledger.
  6. Continue until the model finishes, a configured limit is reached, or the user stops the run.

The session ledger is JSONL, so runs can be inspected, resumed, compacted, or exported without a database.

Code Intelligence

Codog includes an experimental Go-focused code-intelligence layer behind the lsp tool and the /code-intel slash command. Without a configured language server it can answer common Go repository queries from syntax trees and go tool diagnostics, including symbols, definitions, references, hover text, completion candidates, diagnostics, formatting previews, and rename previews.

When a configured LSP server is available, Codog can route supported requests to that server for richer actions such as semantic tokens, code lenses, inlay hints, inline values, code actions, call hierarchy, and type hierarchy. These routes are useful for integration testing and local workflows, but they should be treated as experimental until they have been exercised against the specific server and repository you plan to use.

Configuration

Codog separates shared project defaults from personal settings and local secrets.

Location Purpose
AGENTS.md, CLAUDE.md, CLAW.md Project instructions loaded into the agent context
AGENTS.local.md, CLAUDE.local.md, CLAW.local.md Local instruction overrides
.claude/CLAUDE.md, .claw/CLAUDE.md, .claw/instructions.md, .codog/instructions.md Tool-scoped project instructions
.codog.json Shared project configuration
.codog.local.json Uncommitted local overrides
.codog/commands Project slash commands
.codog/skills Project skills
.codog/hooks Project hook scripts

Repository Scope

Start Codog from the smallest useful package or service directory when possible. For monorepos, this usually means cd services/api instead of starting at the repository root, then using codog add-dir ../shared only for sibling code that the task actually needs. This keeps avoidable files out of context before they burn prompt tokens.

Codog reports first-run scope guidance through codog onboarding. The report calls out heavy/generated paths such as node_modules, dist, build, .next, coverage, logs, dumps, generated, and reports, and explains the active ignore files it found.

Use codog files --output-format json for a lightweight workspace weight preview before a broad prompt. The scope_risk section distinguishes a clean workspace from trees likely to burn tokens quickly, lists concrete token sinks, and recommends narrower scope choices or ignore/cleanup targets.

Use codog scope preview to turn those findings into actionable choices. codog scope apply can switch the current runtime workspace to a safer source subdirectory or append a reversible .codogignore block; codog scope restore returns to the broader workspace. codog scope status reports whether a safer-scope state is currently active.

Ignore-file behavior:

  • .gitignore is honored by grep and glob when respectGitignore is enabled, which is the default, and by ls directory listings.
  • .codogignore, .claudeignore, and .clawignore are honored by ls directory listings for local pruning.

Use project ignore files to exclude generated artifacts, dependency caches, coverage output, logs, dumps, and generated reports from routine discovery.

Common provider variables:

  • CODOG_CONFIG_HOME, CLAUDE_CONFIG_HOME, or CLAUDE_CONFIG_DIR
  • ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or CLAUDE_CODE_OAUTH_TOKEN
  • CODOG_MODEL, ANTHROPIC_MODEL, ANTHROPIC_DEFAULT_MODEL, or CLAUDE_MODEL
  • CODOG_ADVISOR_MODEL or ANTHROPIC_SMALL_FAST_MODEL
  • CODOG_MAX_TOKENS or ANTHROPIC_MAX_TOKENS
  • CODOG_TEMPERATURE or ANTHROPIC_TEMPERATURE
  • CODOG_REASONING_EFFORT or ANTHROPIC_REASONING_EFFORT
  • CODOG_EXTRA_BODY
  • ANTHROPIC_BASE_URL or CODOG_BASE_URL
  • OPENAI_API_KEY and OPENAI_BASE_URL
  • OLLAMA_HOST
  • XAI_API_KEY
  • DASHSCOPE_API_KEY

Keep credentials in environment variables or local-only config. Do not commit API keys, generated sessions, caches, private prompts, or machine-specific paths.

MCP servers can be declared with Codog's mcp_servers key, Claude-style mcpServers, or VS Code-style mcp.servers; all three are normalized into the same runtime server list.

Use codog config help --output-format json to inspect the section names supported by the current binary. The main public sections are:

Section Examples
auth API key, auth token, OAuth profile, base URL
model model, advisor model, token and turn limits, temperature
permissions permission mode, allow and deny rules
sandbox strategy and sandbox runtime options
remote remote control enablement, auth token, lease duration
editor_bridge local IDE bridge socket and token
background worker state file path
preferences Chrome default, notifications, ultra review preference
compatibility counters and URLs for Claude-Code-compatible commands
marketplace plugin marketplace sources and public keys
enterprise managed policy file and verification key
updater release manifest URL for update checks and downloads

Safety Model

Codog separates assistant intent from host execution.

Permission modes include read-only, workspace-write, prompt, danger-full-access, and allow. The default mode should match how much trust you want to give a run: inspect-only work belongs in read-only; edits inside a repository belong in workspace-write; sensitive tool use should go through prompt.

These controls are workflow guardrails. They are not a complete security sandbox for hostile repositories, untrusted commands, or adversarial prompts.

Repository Map

Path Responsibility
cmd/codog CLI entry point
internal/agent Command dispatch, runtime wiring, and the agent loop
internal/anthropic Anthropic-compatible client and message types
internal/tools Shell, file, search, git, and edit tools
internal/session JSONL transcripts, resume, export, and metadata
internal/config User, project, local, and environment configuration
internal/tui Bubble Tea interactive interface
internal/mcp MCP client integration
internal/skills Skill discovery and activation
internal/hooks Local automation hooks
internal/control Remote control and IDE bridge surfaces

Development

The normal validation path is intentionally boring:

scripts/smoke.sh

For narrower checks, run go test ./..., go vet ./..., go build ./cmd/codog, or scripts/install.sh --bin-dir ./bin directly.

Keep changes portable. Avoid committing generated caches, API keys, machine-specific setup snippets, local absolute paths, or tool attribution text.

Mock Parity

codog mock-parity runs deterministic compatibility scenarios without calling a live model provider. A mock provider emits assistant text and tool-use blocks, then Codog executes its real run loop, tools, permissions, hooks, sessions, MCP paths, and reporting surfaces.

Use it when changing core runtime behavior:

codog mock-parity
codog mock-parity manifest --output-format json

The command is not a claim that Codog is identical to Claude Code. It is a repeatable contract for the Claude-Code-style workflows this implementation currently supports.

License

Codog is released under the MIT License.

Directories

Path Synopsis
cmd
codog command
Command codog runs the Codog coding agent CLI.
 Command codog runs the Codog coding agent CLI.
internal
acpserver
Package acpserver implements the JSON-RPC agent control protocol server.
 Package acpserver implements the JSON-RPC agent control protocol server.
agent
Package agent implements Codog's agent runtime, CLI orchestration, and interactive command surfaces.
 Package agent implements Codog's agent runtime, CLI orchestration, and interactive command surfaces.
agentdefs
Package agentdefs loads and validates named sub-agent definitions.
 Package agentdefs loads and validates named sub-agent definitions.
agentruns
Package agentruns records and reads persisted agent run metadata.
 Package agentruns records and reads persisted agent run metadata.
anthropic
Package anthropic implements Anthropic-compatible streaming model clients.
 Package anthropic implements Anthropic-compatible streaming model clients.
anttrace
Package anttrace parses and renders Anthropic request trace data.
 Package anttrace parses and renders Anthropic request trace data.
approval
Package approval models tool approval decisions and permission prompts.
 Package approval models tool approval decisions and permission prompts.
argsub
Package argsub expands command arguments from named runtime variables.
 Package argsub expands command arguments from named runtime variables.
audit
Package audit writes structured records for runtime decisions and tool use.
 Package audit writes structured records for runtime decisions and tool use.
autofixpr
Package autofixpr turns GitHub pull request comments into focused fix prompts.
 Package autofixpr turns GitHub pull request comments into focused fix prompts.
background
Package background manages detached local jobs started by Codog.
 Package background manages detached local jobs started by Codog.
bashvalidation
Package bashvalidation classifies shell commands before execution.
 Package bashvalidation classifies shell commands before execution.
bookmarks
Package bookmarks stores named pointers into Codog workspaces and sessions.
 Package bookmarks stores named pointers into Codog workspaces and sessions.
branchlock
Package branchlock detects branch state that should block unsafe edits.
 Package branchlock detects branch state that should block unsafe edits.
bridge
Package bridge exposes local bridge endpoints for editor and remote clients.
 Package bridge exposes local bridge endpoints for editor and remote clients.
bridgeparity
Package bridgeparity validates the local editor bridge, control API, and remote-session bootstrap surfaces as one readiness contract.
 Package bridgeparity validates the local editor bridge, control API, and remote-session bootstrap surfaces as one readiness contract.
bughunt
Package bughunt builds prompts and reports for focused bug investigation.
 Package bughunt builds prompts and reports for focused bug investigation.
codeintel
Package codeintel provides local code-intelligence helpers for symbols, diagnostics, notebooks, and language-server queries.
 Package codeintel provides local code-intelligence helpers for symbols, diagnostics, notebooks, and language-server queries.
commandrun
Package commandrun executes workspace commands and renders their results.
 Package commandrun executes workspace commands and renders their results.
config
Package config loads Codog configuration from files, environment, and flags.
 Package config loads Codog configuration from files, environment, and flags.
configvalidate
Package configvalidate checks Codog configuration files and reports fixes.
 Package configvalidate checks Codog configuration files and reports fixes.
contextview
Package contextview builds compact workspace context for model prompts.
 Package contextview builds compact workspace context for model prompts.
control
Package control exposes local HTTP and stream handlers for Codog sessions.
 Package control exposes local HTTP and stream handlers for Codog sessions.
cron
Package cron stores recurring task definitions and run history.
 Package cron stores recurring task definitions and run history.
customcommands
Package customcommands loads project and user-defined slash commands.
 Package customcommands loads project and user-defined slash commands.
doclint
Package doclint contains repository-level documentation hygiene tests.
 Package doclint contains repository-level documentation hygiene tests.
doctor
Package doctor runs local environment checks for codog doctor.
 Package doctor runs local environment checks for codog doctor.
envfile
Package envfile parses dotenv-style environment files.
 Package envfile parses dotenv-style environment files.
fileinventory
Package fileinventory indexes workspace files for search and context views.
 Package fileinventory indexes workspace files for search and context views.
focus
Package focus stores scoped context used to steer an agent session.
 Package focus stores scoped context used to steer an agent session.
frontmatter
Package frontmatter parses simple metadata blocks from text files.
 Package frontmatter parses simple metadata blocks from text files.
g004conformance
Package g004conformance reports conformance against the G004 behavior set.
 Package g004conformance reports conformance against the G004 behavior set.
githubcomments
Package githubcomments reads GitHub pull request comments into stable reports.
 Package githubcomments reads GitHub pull request comments into stable reports.
githubsetup
Package githubsetup creates Codog-compatible GitHub Actions setup reports.
 Package githubsetup creates Codog-compatible GitHub Actions setup reports.
gitignore
Package gitignore updates project ignore files with Codog runtime paths.
 Package gitignore updates project ignore files with Codog runtime paths.
gitops
Package gitops wraps common Git status and diff operations.
 Package gitops wraps common Git status and diff operations.
greencontract
Package greencontract records validation requirements for completed work.
 Package greencontract records validation requirements for completed work.
harness
Package harness runs mock parity checks against Codog behavior.
 Package harness runs mock parity checks against Codog behavior.
hookenv
Package hookenv prepares environment variables for Codog hook execution.
 Package hookenv prepares environment variables for Codog hook execution.
hooks
Package hooks loads and runs lifecycle hooks around agent actions.
 Package hooks loads and runs lifecycle hooks around agent actions.
insights
Package insights derives structured observations from sessions and workspaces.
 Package insights derives structured observations from sessions and workspaces.
laneevents
Package laneevents stores timeline events for agent lanes and tasks.
 Package laneevents stores timeline events for agent lanes and tasks.
manifests
Package manifests validates Codog plugin and skill manifest files.
 Package manifests validates Codog plugin and skill manifest files.
mcp
Package mcp manages Model Context Protocol server configuration and calls.
 Package mcp manages Model Context Protocol server configuration and calls.
mcpauthdiag
Package mcpauthdiag builds recovery-oriented MCP authentication reports.
 Package mcpauthdiag builds recovery-oriented MCP authentication reports.
mcpserver
Package mcpserver serves Codog tools through the Model Context Protocol.
 Package mcpserver serves Codog tools through the Model Context Protocol.
memory
Package memory stores searchable project and session memory entries.
 Package memory stores searchable project and session memory entries.
mockanthropic
Package mockanthropic serves deterministic Anthropic-compatible test streams.
 Package mockanthropic serves deterministic Anthropic-compatible test streams.
mocklimits
Package mocklimits defines deterministic limits for mock provider behavior.
 Package mocklimits defines deterministic limits for mock provider behavior.
modelrouting
Package modelrouting selects provider routes and model settings.
 Package modelrouting selects provider routes and model settings.
nudges
Package nudges tracks lightweight user-facing guidance and follow-up prompts.
 Package nudges tracks lightweight user-facing guidance and follow-up prompts.
oauth
Package oauth implements local OAuth device, browser, and token flows.
 Package oauth implements local OAuth device, browser, and token flows.
onboarding
Package onboarding inspects workspaces and builds first-run setup guidance.
 Package onboarding inspects workspaces and builds first-run setup guidance.
orchestrationparity
Package orchestrationparity summarizes local multi-agent, plugin, skill, and MCP readiness as one productionization contract.
 Package orchestrationparity summarizes local multi-agent, plugin, skill, and MCP readiness as one productionization contract.
outputstyle
Package outputstyle loads and applies named response style settings.
 Package outputstyle loads and applies named response style settings.
pathscope
Package pathscope checks whether filesystem paths are inside allowed roots.
 Package pathscope checks whether filesystem paths are inside allowed roots.
perfissue
Package perfissue builds reports for suspected performance problems.
 Package perfissue builds reports for suspected performance problems.
planmode
Package planmode persists planning state for interactive Codog sessions.
 Package planmode persists planning state for interactive Codog sessions.
plugins
Package plugins installs, validates, and loads Codog plugin bundles.
 Package plugins installs, validates, and loads Codog plugin bundles.
policyengine
Package policyengine evaluates workspace and enterprise policy rules.
 Package policyengine evaluates workspace and enterprise policy rules.
powershellvalidation
Package powershellvalidation checks PowerShell commands before execution.
 Package powershellvalidation checks PowerShell commands before execution.
projectinit
Package projectinit creates starter Codog configuration for a workspace.
 Package projectinit creates starter Codog configuration for a workspace.
projectscope
Package projectscope discovers project roots and workspace-scoped paths.
 Package projectscope discovers project roots and workspace-scoped paths.
prompthistory
Package prompthistory records recent prompts for reuse and inspection.
 Package prompthistory records recent prompts for reuse and inspection.
promptrefs
Package promptrefs resolves file and symbol references embedded in prompts.
 Package promptrefs resolves file and symbol references embedded in prompts.
providerdiag
Package providerdiag diagnoses provider credentials and endpoint settings.
 Package providerdiag diagnoses provider credentials and endpoint settings.
provisional
Package provisional deduplicates in-flight status acknowledgements while retaining raw audit events.
 Package provisional deduplicates in-flight status acknowledgements while retaining raw audit events.
prworkflow
Package prworkflow supports pull request review and follow-up workflows.
 Package prworkflow supports pull request review and follow-up workflows.
recovery
Package recovery stores retry recipes and recovery state for failed runs.
 Package recovery stores retry recipes and recovery state for failed runs.
releasenotes
Package releasenotes formats release note entries from repository changes.
 Package releasenotes formats release note entries from repository changes.
releaseparity
Package releaseparity summarizes release, sandbox, updater, and managed policy readiness for production delivery audits.
 Package releaseparity summarizes release, sandbox, updater, and managed policy readiness for production delivery audits.
remote
Package remote stores remote session setup and transport configuration.
 Package remote stores remote session setup and transport configuration.
reportconformance
Package reportconformance validates downstream consumer behavior for reporting projections.
 Package reportconformance validates downstream consumer behavior for reporting projections.
reporting
Package reporting normalizes structured reports and projection metadata.
 Package reporting normalizes structured reports and projection metadata.
reportschema
Package reportschema defines shared schemas for structured runtime reports.
 Package reportschema defines shared schemas for structured runtime reports.
review
Package review builds code review prompts and parses review output.
 Package review builds code review prompts and parses review output.
roadmap
Package roadmap maps parity goals to concrete Codog capability checkpoints.
 Package roadmap maps parity goals to concrete Codog capability checkpoints.
runloop
Package runloop coordinates repeated agent turns and stop conditions.
 Package runloop coordinates repeated agent turns and stop conditions.
saferscope
Package saferscope plans safe workspace boundary changes.
 Package saferscope plans safe workspace boundary changes.
sandbox
Package sandbox configures platform-specific execution constraints.
 Package sandbox configures platform-specific execution constraints.
securityreview
Package securityreview builds prompts and summaries for security analysis.
 Package securityreview builds prompts and summaries for security analysis.
session
Package session persists JSONL conversations and related session metadata.
 Package session persists JSONL conversations and related session metadata.
sessionname
Package sessionname creates stable display names for Codog sessions.
 Package sessionname creates stable display names for Codog sessions.
sessionsummary
Package sessionsummary stores compact summaries for resumed sessions.
 Package sessionsummary stores compact summaries for resumed sessions.
shellstate
Package shellstate records shell working directories and environment state.
 Package shellstate records shell working directories and environment state.
ship
Package ship prepares commit, push, and pull request delivery workflows.
 Package ship prepares commit, push, and pull request delivery workflows.
signing
Package signing verifies and records signatures for trusted artifacts.
 Package signing verifies and records signatures for trusted artifacts.
skills
Package skills discovers and renders Codog skill instructions.
 Package skills discovers and renders Codog skill instructions.
slash
Package slash defines built-in slash commands and matching helpers.
 Package slash defines built-in slash commands and matching helpers.
status
Package status builds and renders structured Codog runtime status reports.
 Package status builds and renders structured Codog runtime status reports.
taskpacket
Package taskpacket serializes portable task packets for agent handoff.
 Package taskpacket serializes portable task packets for agent handoff.
team
Package team coordinates grouped background tasks for multi-agent workflows.
 Package team coordinates grouped background tasks for multi-agent workflows.
templates
Package templates manages reusable Codog artifact and prompt templates.
 Package templates manages reusable Codog artifact and prompt templates.
terminalparity
Package terminalparity summarizes interactive terminal readiness for parity audits and machine-readable capability reports.
 Package terminalparity summarizes interactive terminal readiness for parity audits and machine-readable capability reports.
terminalsetup
Package terminalsetup detects shell integration and terminal capabilities.
 Package terminalsetup detects shell integration and terminal capabilities.
thinkback
Package thinkback stores reflection notes for later agent context.
 Package thinkback stores reflection notes for later agent context.
todos
Package todos stores session-scoped todo lists.
 Package todos stores session-scoped todo lists.
toolnames
Package toolnames provides shared helpers for canonical tool-name handling.
 Package toolnames provides shared helpers for canonical tool-name handling.
tools
Package tools registers workspace, shell, MCP, and agent tool implementations.
 Package tools registers workspace, shell, MCP, and agent tool implementations.
trustresolver
Package trustresolver resolves workspace trust decisions from policy inputs.
 Package trustresolver resolves workspace trust decisions from policy inputs.
tui
Package tui implements Codog's Bubble Tea terminal interface.
 Package tui implements Codog's Bubble Tea terminal interface.
undo
Package undo records reversible file edits and applies rollbacks.
 Package undo records reversible file edits and applies rollbacks.
updater
Package updater verifies and applies Codog update manifests and artifacts.
 Package updater verifies and applies Codog update manifests and artifacts.
usage
Package usage tracks model token and cost estimates.
 Package usage tracks model token and cost estimates.
verifiers
Package verifiers runs configured validation commands for a workspace.
 Package verifiers runs configured validation commands for a workspace.
versioninfo
Package versioninfo reports build and update metadata for the CLI.
 Package versioninfo reports build and update metadata for the CLI.
webaccess
Package webaccess applies policy decisions to network access requests.
 Package webaccess applies policy decisions to network access requests.
workers
Package workers coordinates local worker registrations and heartbeats.
 Package workers coordinates local worker registrations and heartbeats.
workerstate
Package workerstate records worker lifecycle and readiness state.
 Package workerstate records worker lifecycle and readiness state.
workspaceops
Package workspaceops provides bounded filesystem operations for a workspace.
 Package workspaceops provides bounded filesystem operations for a workspace.
worktree
Package worktree manages Git worktree metadata for parallel agent work.
 Package worktree manages Git worktree metadata for parallel agent work.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.