Run Kimchi headless

Run Kimchi Coding from scripts and CI with the --print flag: pass a prompt, capture the answer from stdout, control what the run may do, and handle exit codes.

Kimchi runs as an interactive terminal session by default. In headless mode it processes a single prompt, writes the answer to stdout, and exits. Use headless mode to run Kimchi from shell scripts, CI pipelines, and other automation that supplies the task and consumes the result.

A headless run has no human in the loop. Kimchi cannot ask you questions, and approval prompts cannot appear. This page shows how to pass the prompt, what a run may do without you, and how to wire the runs into scripts.

Before you start

You need Kimchi installed. See Kimchi TUI for install instructions.

A headless run needs a Kimchi API key. It also skips the first-run setup wizard, so the key must be in place where the run starts.

CI and scripts. Pass the key as the KIMCHI_API_KEY environment variable:

export KIMCHI_API_KEY="your-key"

In GitHub Actions, map a repository secret to the variable:

env:
  KIMCHI_API_KEY: ${{ secrets.KIMCHI_API_KEY }}

Your machine. Run kimchi setup (or kimchi login) once, or add the key to the apiKey field in ~/.config/kimchi/config.json:

{
  "apiKey": "your-key"
}

Kimchi reads the key in this order: the KIMCHI_API_KEY environment variable, the .kimchi/config.json file in a trusted working directory, and the global ~/.config/kimchi/config.json.

Confirm the setup before you wire up CI. The reply on stdout confirms the install and the key:

kimchi -p "Reply with OK"

A headless run executes in the directory you launch it from; you do not need any project setup. When the directory holds a Kimchi project, Kimchi loads its configuration only from a trusted directory. Project trust fails closed in a headless run: pass --approve to trust the directory for a single run:

kimchi -p "Summarize this repository" --approve

An interactive session can save the trust decision, so later runs need no flag.

Run a prompt headlessly

Run a one-off prompt with -p (short for --print):

kimchi -p "Summarize the uncommitted changes in this repository"

The run writes the answer to stdout and exits with code 0. Diagnostics, when present, go to stderr. The run records a session file unless you pass --no-session.

Pass the prompt on stdin

In a pipeline, pass the prompt on stdin and omit the prompt:

cat task.md | kimchi -p

Select a model and thinking level

Pass --model with any model id from kimchi --list-models:

kimchi -p "Summarize the uncommitted changes in this repository" --model kimi-k3

Set the reasoning effort with --thinking (off, minimal, low, medium, high, xhigh, max):

kimchi -p "Reply with OK" --thinking low

Steer behavior with a system prompt addition

Pass extra standing instructions with --append-system-prompt:

kimchi -p "Review src/api for naming inconsistencies" --append-system-prompt "Follow the naming conventions in CONTRIBUTING.md"
⚠️

Place the prompt immediately after -p. Mode flags such as --auto, --yolo, and --ferment-oneshot can consume the prompt text that follows them. The run then exits with code 0 and produces no output. Pass the prompt directly after -p. In a script, pipe the prompt over stdin and check that stdout is not empty before you treat exit code 0 as success.

Control what a run may do

A headless run cannot show approval prompts. Read-only tools run without approval. Kimchi evaluates every other tool call automatically: it runs the calls that the evaluation allows and blocks the calls that would need your confirmation.

A blocked call does not stop the run. The model sees the block, then works around it or reports it, and the run still exits with code 0.

The KIMCHI_PERMISSIONS environment variable selects the permission mode: default, plan, auto, or yolo. The plan mode restricts a run to read-only planning. In a headless run, auto evaluates tool calls the same way default does. Automation that must name an execution mode, such as a Ferment one-shot, uses it.

Start with read-only prompts. They need no permission settings:

kimchi -p "List unused exports in src/ and explain why each is likely dead code"

To let every tool call run without evaluation, start the run in yolo mode with the KIMCHI_PERMISSIONS environment variable:

KIMCHI_PERMISSIONS=yolo kimchi -p "Fix the failing test in src/utils.ts and run the test suite"
⚠️

In yolo mode, tool calls run without evaluation. Deny rules still apply. Use yolo mode only for disposable environments you fully control.

Restrict a run with deny rules. A rule names a tool, optionally with a matcher; a bare program name such as curl also matches bash commands that invoke it.

This run blocks both fetch routes, and the model reports the block instead of guessing:

kimchi -p "Use the web_fetch tool to load https://example.com and reply with the page title" --deny-tool "web_fetch,curl"
I couldn't complete the fetch. Both attempts were blocked:

1. web_fetch on https://example.com → Denied by rule web_fetch [cli]
2. Fallback curl via bash → Denied by rule curl [cli]

So I have no fetched data to report the title from.

--allow-tool adds allow rules the same way:

kimchi -p "Run the test suite and reply with a summary of the failures" --allow-tool "bash"

Deny rules always win over allow rules.

Kimchi hard-blocks dangerous commands before execution, regardless of permission mode. The run reports the block and exits with code 0:

kimchi -p "Run this exact shell command: sudo rm -rf /tmp/scratch"
I could not run it. The command is blocked before execution.

sudo rm -rf /tmp/scratch < /dev/null
→ Hard-blocked program in command: sudo

Collect answers and artifacts

Write the answer to a file with shell redirection:

kimchi -p "Compare the operations in openapi.yaml to the client methods in src/client.ts and list the mismatches" > drift.md

For data you want to process further, have the run write a file, then check it with a deterministic tool:

kimchi -p "Write the direct dependencies to deps.json as an array of objects with name and version fields"
jq -e 'type == "array"' deps.json

--mode json and --mode rpc emit internal protocol streams for tool builders, not summaries for scripts. Keep scripts on stdout and files. See ACP for the protocol that IDE integrations use.

Run in CI

A GitHub Actions workflow that installs Kimchi, runs a weekly audit from a secret, and uploads the report:

name: Kimchi code audit
on:
  schedule:
    - cron: "0 4 * * 1"
  workflow_dispatch:
permissions:
  contents: read
jobs:
  audit:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v4
        with:
          persist-credentials: false
      - name: Install Kimchi
        run: |
          curl -fsSL https://github.com/getkimchi/kimchi/releases/latest/download/install.sh | KIMCHI_INSTALL_DIR="$HOME/.local/bin" bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - name: Run the audit
        env:
          KIMCHI_API_KEY: ${{ secrets.KIMCHI_API_KEY }}
          KIMCHI_TELEMETRY_ENABLED: "0"
        run: |
          kimchi -p "List unused exports in src/ and write the findings to audit.md as a Markdown table"
      - uses: actions/upload-artifact@v4
        with:
          name: audit-report
          path: audit.md

These environment variables cover the common CI needs:

VariableEffect
KIMCHI_API_KEYAuthenticates the run without kimchi setup.
KIMCHI_TELEMETRY_ENABLED=0Turns telemetry off for the run.
KIMCHI_NO_UPDATE_CHECK=1Disables the background update probe.
KIMCHI_TAGS=ci:nightly,team:platformTags every request for cost reporting. See Tags.
HTTP_PROXY / HTTPS_PROXYRoutes the run's requests through a proxy.

The exit code tells your script whether the run finished:

Exit codeMeaning
0The run delivered its answer.
74The provider failed after automatic retries. Re-run the command.
OtherThe run failed. Check stderr for the error message.
⚠️

Exit code 0 means the run finished, not that the task happened. A blocked action or a "done" claim can still leave the work undone. Check the artifacts: run the tests, or read written files with jq or a linter.

Fan out over many files with xargs. Each file gets its own run:

git ls-files '*.py' | xargs -P 4 -I {} env KIMCHI_TELEMETRY_ENABLED=0 kimchi -p "Check that {} starts with the license header in LICENSE.header. Add the header if it is missing. Change nothing else."

Set KIMCHI_TELEMETRY_ENABLED=0 so every run in the loop prints its answer.

A few practices keep unattended runs predictable:

  • Start with read-only prompts and file output. Add permission modes only when a run must change things.
  • Commit and push from your own script steps, not from inside an unsupervised run.
  • Check every artifact with a deterministic tool before you rely on it.
  • Keep the prompt directly after -p in every scripted command.

Run a Ferment one-shot in CI

Ferment automates multi-step projects across sessions. See Ferment for the interactive workflow. The one-shot form runs a complete ferment without interactive input: Kimchi scopes the plan, executes it phase by phase, and exits when the ferment completes. Pass --ferment-oneshot together with an execution permission mode:

KIMCHI_PERMISSIONS=auto kimchi -p "Add OpenAPI spec export to the REST API" --ferment-oneshot

The run prints a completion summary when the ferment finishes:

Ferment "Add OpenAPI spec export" is complete — final grade A (all gates pass).

Your organization policy controls automated ferment runs. When the policy does not allow an execution mode, the run refuses with an error and does not start a ferment. Without KIMCHI_PERMISSIONS, the run refuses the same way. See Set permissions for unattended runs for the mode values.

The Ferment reference covers the ferment state file, one-shot runs, and attaching a ferment at startup with KIMCHI_ACTIVE_FERMENT.

Next steps


Did this page help you?