Every command and flag on this page was verified against the clap
definitions in src/main.rs and by running the binary. When the binary and
this page disagree, the binary is authoritative — check codegg --help and
codegg <command> --help.
Run codegg --help for the current top-level surface and
codegg <command> --help for any subcommand.
- Running without a subcommand
- Global flags
- Sessions
- Providers and credentials
- Configuration and diagnostics
- Daemon
- Non-interactive use
- MCP, ACP and plugins
- Research
- Shell completions
- Upgrade
- Tool advisor
- Hidden compatibility spellings
With no subcommand, codegg opens the TUI. These startup forms are the
common ones:
codegg # start a new session
codegg -c # resume the most recent session
codegg -s <session-id> # open a specific session
codegg --fork <session-id> # fork a session
codegg --no-session # ephemeral run, no persistence
codegg -m anthropic/claude-sonnet-4-20250514 # pick a model
codegg -a build # pick an agent
codegg --cwd /path/to/project # choose the workspace
codegg -m anthropic/claude-sonnet-4-20250514 --run "Explain this project" # one prompt, then exit--model accepts either provider/model-id or a bare model-id. The
provider/model form is unambiguous and is what the examples here use.
| Flag | Meaning |
|---|---|
-c, --continue-session |
Resume the most recent session. Conflicts with --session, --fork, --no-session. |
-s, --session <SESSION> |
Open a specific session. |
--fork <FORK> |
Fork the given session. |
--no-session |
Ephemeral run; nothing is persisted. |
-m, --model <MODEL> |
Override the model. |
-a, --agent <AGENT> |
Override the agent. |
-p, --run <PROMPT> |
Run a single prompt and exit. |
-f, --format <text|json> |
Output format for one-shot mode. --output-format is a compatibility alias. Default text. |
-q, --quiet |
Hide status messages in non-interactive mode. |
--cwd <DIRECTORY> |
Set the working directory before startup. Must exist, or the command fails. Equivalent to launching from that directory. |
--cwd chooses the initial workspace. During a session, the model-facing
session_working_directory tool can persist a default subdirectory within
that workspace; it does not change project identity or the workspace security
boundary. Use an authorized launch, fork, or session switch to change roots.
| -v | Verbosity: no flag warn, -v info, -vv debug, -vvv+ trace. |
| --approval-mode <MODE> | interactive, automatic, or yolo. |
| --sandbox <PROFILE> | read-only, workspace-write, or full-host. |
| --yolo | Exact alias for --approval-mode yolo. |
| --standalone | Run the core in-process, without the singleton daemon. |
Approval mode and sandbox are orthogonal: an automatic approval mode never
implies host-level filesystem access. A constrained Bash or Python command is
refused when the host cannot apply its OS filesystem sandbox; it is not run
without containment. Use full-host only when you intend to opt out of CodeGG
filesystem containment. Constrained processes receive private temporary space;
shared /tmp and global user caches are not writable grants. Filesystem
containment does not isolate network access or every IPC channel; Seatbelt also
allows broad reads and preserves descriptors opened before confinement. See
architecture/security.md for backend-specific guarantees and limits, and
docs/tui.md for approval controls.
codegg sessions # list sessions for the current project
codegg sessions --archived # include archived sessions
codegg session <session-id> # inspect one session
codegg export <session-id> # export to stdout
codegg export <session-id> -o session.json
codegg import session.json # import a sessionThese commands read and write the project-local store at
<project>/.codegg/sessions.db. The database is created and migrated on
first use — by the TUI, the daemon, or any of these commands — so they work
in a project that has never been opened.
Sessions created by the TUI are persistent by default and can be resumed across restarts.
codegg launch --project <project-id> # new session, fresh checkout
codegg launch --project <project-id> --branch feature/x # on a named branch
codegg launch --project <project-id> --base main # from a base branch or tag
codegg launch --project <project-id> --fork <session-id> # fork history into a new checkout
codegg launch --project <project-id> --worktree <worktree-id> # use an existing checkout
codegg launch --project <project-id> --idempotency-key k1 # retry-safe launchcodegg launch places a session in an isolated managed checkout. It
goes through the daemon, because the daemon owns the durable launch
record, the worktree service and the workspace registry.
The launch is idempotent: a retry with the same --idempotency-key
and the same request converges on the original launch instead of
allocating a second checkout. A retry with the same key and a different
request is refused. Without --idempotency-key, every invocation is a
distinct launch.
--worktree new (the default) allocates a fresh managed checkout;
--worktree <worktree-id> adopts a checkout the caller is already
authorized for. --base names a branch or tag to create the checkout
from; --branch names the branch to create it on.
Shared-checkout execution is not available: a launch always places the session in its own isolated checkout.
codegg providers # list providers your config can use
codegg models # list models across configured providers
codegg models -p anthropic # list one provider's modelsThese read your actual configuration and credentials rather than a static
list, so the output changes with what you have configured. See
docs/providers.md.
The encrypted credential store:
printf '%s' "$OPENAI_API_KEY" | codegg auth set-key openai
codegg auth status # account ids only; never secrets
codegg auth logout openaiauth set-key reads the key from stdin, so it does not appear in shell
history. On a fresh profile the first protected write creates a CodeGG-managed
master key automatically — no key environment variable is required. See
docs/providers.md for the full resolution order.
codegg validate # validate the auto-detected config
codegg validate --config ./my.jsonc # validate a specific file
codegg edit # open the config in $EDITOR
codegg edit --config ./my.jsonc # open a specific file
codegg edit --project # open the project-local config
codegg edit --editor hx # override $VISUAL/$EDITOR
codegg doctor # run every diagnostic subsystem
codegg doctor providers # one subsystemedit opens a config file in your editor, creating it (and its directory)
first if it does not exist so the editor always gets a real path to write.
The editor is resolved in this order:
--editor <cmd>$VISUAL$EDITOR- the first of
hx,vim,vi,nanofound onPATH
$VISUAL outranks $EDITOR per the usual Unix convention, because $VISUAL
marks the full-screen editor you prefer for interactive editing while
$EDITOR is often left as a line-oriented default. Both may be multi-word or
quoted (EDITOR="code --wait", EDITOR="/opt/My Editor/hx"). An editor named
by $VISUAL/$EDITOR is used even if it is missing — CodeGG reports the spawn
failure rather than silently editing the file in a different program.
Which file gets opened, highest precedence first: --config <path>, then a
project config discovered from the working directory (.codegg/codegg.jsonc),
then the global config. --project forces the project-local file, creating it
if no project config exists yet.
After the editor exits, edit re-reads the file and reports whether it still
parses. A parse or validation failure is printed to stderr but does not change
the exit status — the edit itself succeeded, and you may still be fixing it.
Run codegg validate to confirm.
doctor takes an optional positional subsystem:
| Subsystem | What it reports |
|---|---|
all |
Everything below (the default). |
search |
eggsearch backend, MCP tool coverage, output caps, provider degradation. |
mcp |
Configured MCP servers and their connection state. |
lsp |
Language-server registry and per-gate exposure state. |
deterministic-tools |
eggsact backend, profile, and tool visibility counts. |
providers |
Configured providers. Read-only; makes no network probes. |
credentials |
Stored credential metadata. Never prints secrets. |
installation |
Owned runfiles, helper/sidecar state, and the sandbox kernel probe. |
doctor exits 0 even when it reports problems — read the output rather than
the exit code.
--subsystem <name> still parses as a deprecated alias for the positional
form. Prefer the positional spelling.
codegg daemon status # is it running, and where
codegg daemon logs # tail recent daemon logs
codegg daemon logs --lines 200
codegg daemon start # run the daemon (BLOCKS - see below)
codegg daemon stop # stop it
codegg daemon attach # attach the TUI to it
codegg daemon attach --new # attach with a new session
codegg daemon scratch-usage # measure the daemon-owned scratch cache
codegg daemon scratch-reclaim --tree <digest> # dispose of one scratch treecodegg daemon start runs in the foreground. It acquires the singleton
lock, binds the socket, and then stays in the foreground for the life of the
daemon — it does not fork or detach. Run it in a separate terminal or
background it. If a healthy daemon already holds the lock, the command prints
a message and exits 0 rather than starting a second instance.
You rarely need to do this by hand: a plain codegg connects to an existing
daemon or starts one automatically. See docs/daemon.md.
codegg daemon scratch-usage # the daemon's last snapshot
codegg daemon scratch-usage --refresh # take a fresh measurement
codegg daemon scratch-usage --json # machine-readable report
codegg daemon scratch-reclaim --tree <digest> # dry run: reports, removes nothing
codegg daemon scratch-reclaim --tree <digest> --apply # actually remove itscratch-usage reports the daemon's disposable scratch cache: tree count,
total size, age, and whether the reclaim path would accept each tree. The
daemon answers from its own snapshot unless --refresh asks for a fresh
measurement. scratch-reclaim names a tree by the opaque digest that
scratch-usage reports; without --apply it is a dry run that removes
nothing. Both commands accept --endpoint and --json.
One-shot prompt:
codegg --run "Summarize the changes in this repository"
codegg --run "Summarize the changes" --format jsonStructured input for CI, via exec:
printf '%s\n' '{"prompt":"Review this repository","model":"anthropic/claude-sonnet-4-20250514","agent":"build"}' \
| codegg exec --format json --quietThe same payload can be passed with --json '<payload>' or read from a file
with --file <path> instead of stdin. The object has three optional string
fields — prompt (required), model, and agent.
codegg exec --json '{"prompt":"List the public functions in src/lib.rs"}' -qexec also takes -s <session-id> to resume an existing session, and the
same policy flags as the root command:
codegg exec --approval-mode interactive --sandbox read-only --quiet \
--json '{"prompt":"Summarize src/main.rs"}'--json-output / -j remain as compatibility aliases for --format json.
Without explicit policy flags, exec keeps its legacy permissive behavior for
existing CI pipelines — set --approval-mode and --sandbox explicitly if you
want a bounded run.
codegg mcp list
codegg mcp add
codegg mcp remove
codegg mcp enable
codegg mcp debugMCP servers are configured under the mcp key in the config file. See
docs/MCP.md.
For editor and harness integration, CodeGG speaks ACP v1 over newline-delimited JSON-RPC on stdio:
codegg acpWithout policy flags, ACP keeps the daemon's current policy. An unattended ACP trial can explicitly request one supported envelope:
CODEGG_DAEMON_HOME=/tmp/codegg-private-lane \
codegg acp --approval-mode yolo --sandbox workspace-writePolicy flags use the same parser as exec. Explicit ACP overrides require an
explicit CODEGG_DAEMON_HOME, are serialized against other ACP policy trials
for that root, and fail if the daemon reports a narrower effective policy.
Use a private daemon root, as the developer harness does; the override is
persisted in that daemon's principal preference store. Explicit deterministic
denies, hard-denies, authorization, and sandbox enforcement remain active.
Turn failures are returned as JSON-RPC errors, not ACP cancelled results.
The developer-only multi-lane supervisor is not part of the shipped binary. From a CodeGG checkout, build a candidate and run:
cargo build --bin codegg
python3 -m dev.harness_lab doctor --binary target/debug/codegg
python3 -m dev.harness_lab smoke --binary target/debug/codegg --subjects 2
python3 -m dev.harness_lab smoke --binary target/debug/codegg --subjects 2 --unattended-profile workspace-write
python3 -m dev.harness_lab smoke --binary target/debug/codegg --subjects 2 --unattended-profile full-host
python3 -m dev.harness_lab tool-trial --binary target/debug/codegg --profile workspace-write
python3 -m dev.harness_lab tool-trial --binary target/debug/codegg --profile workspace-write --deny-bash
python3 -m dev.harness_lab evaluate --binary target/debug/codegg --suite dev/harness_lab/fixtures/smoke.jsonl --ledger /tmp/codegg-ledger --candidate baseline
python3 -m dev.harness_lab report --ledger /tmp/codegg-ledger
python3 -m dev.harness_lab improve --proposer manual --max-iterations 1 --dry-runIt uses temporary roots outside the checkout by default. The ordinary smoke
does not submit a model turn or call a provider; policy-profile runs verify
the daemon's requested/effective snapshot but also do not submit a turn. The
turn-level fixture uses a loopback OpenAI-compatible provider and the native
broker, with explicit-deny coverage. Ledger report/replay/compare run offline.
Candidate proposals use a separate linked worktree; OpenCode is version-pinned
to the qualified CLI adapter and candidate acceptance still requires build,
ACP qualification, and paired-ledger gates. See dev/harness_lab/README.md for
the path inventory and platform limits.
Plugins are configured through the plugin config key and managed from the
TUI; there is no codegg plugins CLI subcommand. WASM plugin execution
requires the plugins Cargo feature. See docs/PLUGINS.md.
codegg research "What changed in SQLite's WAL mode since 3.22?"
codegg research "..." --depth deep --audience engineer --allow-network| Flag | Default | Meaning |
|---|---|---|
--mode <MODE> |
narrow-answer |
Research mode. |
--audience <AUDIENCE> |
human |
Target audience for the write-up. |
--depth <DEPTH> |
medium |
Research depth. |
--output <OUTPUTS> |
— | Output profile; repeatable. |
--source <SOURCES> |
— | local, file:<path>, or url:<https-url>. Repeatable. |
--allow-network |
off | Permit network fetching. |
Research depends on the eggsearch backend; check codegg doctor search first
if a query returns nothing.
codegg completions bash # print to stdout
codegg completions zsh -o ~/.zsh/completions # write _codegg into an existing dirWith no -o/--output, the script is written to stdout, not to a file.
--output requires the directory to already exist and names the file per shell
(codegg.bash, _codegg, codegg.fish, codegg.ps1, codegg.elv).
Supported shells: bash, elvish, fish, powershell, zsh. The command's
own help prose lists only four — elvish appears solely in the possible values
line, so trust the value list rather than the sentence.
codegg upgradeUpdates a managed prebuilt installation as a single verified transaction. It
does not fetch or run install.sh. Source installs have no managed bundle to
upgrade; use cargo install again instead. See docs/install.md.
The tool-selection advisor is a diagnostic surface, not a runtime switch. It reports the effective discovery policy and runs the offline corpus tooling.
codegg tool-advisor status # effective policy and decision backend
codegg tool-advisor status --json
codegg tool-advisor bench # keyword baseline over the corpus
codegg tool-advisor bench --bm25 --json # BM25 variant, machine-readable
codegg tool-advisor bench --dataset <path> # a specific JSONL dataset
codegg tool-advisor lint --dataset <path> # corpus floors and split coverage
codegg tool-advisor inspect --model <path> # an SDM local artifact
codegg tool-advisor data status # captured-training-data state
codegg tool-advisor data inspect # captured events as JSON
codegg tool-advisor data export --output <file>
codegg tool-advisor data purgetool-advisor bench defaults to the reviewed repository corpus when no
--dataset is given. tool-advisor inspect needs the optional
decision-runtime-sdm Cargo feature and is refused without it. data export
requires --output; data purge removes the locally captured events.
Both of these exist only in a build with the server Cargo feature.
codegg server --host 127.0.0.1 --port 3000 --standalone-core
codegg attach http://localhost:3000 --token <token>codegg server refuses to start unless --standalone-core is given: the HTTP
server does not proxy to the singleton daemon. codegg attach is the remote
HTTP client; it takes a server URL and an optional --token. The local socket
equivalent is codegg daemon attach, which is always available.
Hidden compatibility spellings
These still parse but are hidden from --help. They exist so existing scripts
and older configurations keep working; prefer the canonical spelling.
| Hidden | Canonical |
|---|---|
--core-transport inproc|stdio|socket |
--standalone, --stdio, codegg daemon attach |
--stdio |
(compatibility stdio core transport) |
--core-endpoint <URI> |
--endpoint on codegg daemon subcommands |
codegg attach-daemon |
codegg daemon attach |
codegg core-stdio |
(internal transport) |
--output-format <FMT> |
--format |
--json-output / -j |
--format json |
doctor --subsystem <NAME> |
doctor <NAME> |
codegg attach is a different command entirely — it is the feature-gated
remote HTTP client, takes a server URL, and only exists in server builds.
See docs/daemon.md and architecture/server.md.
Checked 2026-10-23 against the clap definitions in src/main.rs (the
Cli, Commands, ToolAdvisorCommand, ToolAdvisorDataCommand,
AuthSubcommand, DoctorSubsystem, OutputFormat, CoreTransport, and
DaemonCommand types) and the MCP subcommand enum in src/mcp/cli.rs.
- Top-level flags:
src/main.rsCliandExecutionPolicyArgs(-c/--continue-session,-s/--session,--fork,--no-session,-m/--model,-a/--agent,-p/--run,-f/--formatwith the--output-formatalias,-q/--quiet,--cwd,-v,--approval-mode,--sandbox,--yolo,--standalone). - Subcommands:
src/main.rsCommands—sessions,session,launch,export,import,providers,models,upgrade,tool-advisor,doctor,auth,validate,edit,exec,acp,completions,mcp,research,daemon, plus theserver/attachpair that is gated on theserverCargo feature. daemon startforeground behaviour and the "already running" exit:src/main.rsrun_daemon.daemon stopis Unix-only;codegg serverrefuses to start without--standalone-core(exit code 2):src/main.rscmd_server.daemon scratch-usage/scratch-reclaimflags (--refresh,--json,--tree,--apply,--endpoint):src/main.rsDaemonCommand.tool-advisorsubcommands and thedecision-runtime-sdmrefusal forinspect:src/main.rscmd_tool_advisor.doctorsubsystem list and the "exits 0 even when it reports problems" behaviour:src/main.rscmd_doctor.edittarget-path precedence, thehx/vim/vi/nanofallback order, and "re-reads the file, does not change the exit status":src/main.rsedit_target_pathandcmd_edit.completionssupported shells (bash,elvish,fish,powershell,zsh) and the per-shell output file names:src/main.rscmd_completions.upgradebehaviour (a managed-install transaction, notinstall.sh):src/upgrade/mod.rs.- Session store path
<project>/.codegg/sessions.db:crates/codegg-core/src/storage/mod.rs. mcpCLI verbs (list,add,remove,enable,debug) and the--server-type,-c,-a,-uflags:src/mcp/cli.rs.researchflags and their defaults:src/main.rsCommands::Research.- There is no
codegg pluginssubcommand and nocodegg mcp serversspelling:src/main.rsCommands.