jeo-code autonomous coding-agent hero illustration

Encode intention. Decode software.
A Bun-based AI coding-agent CLI — interviews, reviewed plans, gated execution, honest verification.

license runtime zero native deps

jeo-code character mascot

English · 한국어 · 日本語 · 中文

Run jeo inside a repository and it reads files, edits them, runs commands, and drives the task to completion — streaming every step live in an inline, scrollback-friendly TUI.

• Multi-provider, one loop — Anthropic / OpenAI (+Codex) / Gemini / Antigravity / Ollama behind a uniform JSON tool loop. OAuth login from the input box (/provider login), every model pick persists as the new default.
• Edit integrity — read output carries content anchors (42ab|); anchored edits are verified against the current file, re-mapped when lines shifted, and rejected with fresh content instead of corrupting.
• Self-correcting verification loop — configure a post-edit hook (tsc / eslint / tests) and the agent sees the diagnostics and fixes them in-loop; a red hook blocks done until resolved.
• Real gates, no theater — ralplan consensus is a repo-grounded critic subagent whose [OKAY] verdict is persisted and required by jeo approve; ultragoal reports honestly (a suite run is a global signal, never fabricated per-criterion passes).
• Crash-durable, local-first — all state under .jeo/ with atomic writes, cross-process run locks, failed-task markers with partial-edit warnings on resume.
• Dynamic step budget — turns extend while the tool window shows novel progress and consolidate gracefully when stalled; subagents keep exact step contracts.
• Inline TUI — completed work flushes into real scrollback (tmux wheel works mid-turn), the normal query input box stays visible and editable while the agent runs, Ctrl+O toggles full detail, themes, clipboard image paste (Ctrl+V), CJK/emoji-safe width math.

Requires Bun 1.3.14+.

bun install -g jeo-code
jeo --version

jeo # interactive agent in the current repo
jeo "Tidy the README and run the tests" # one-shot request
jeo doctor # config + live model connectivity check
jeo setup # API keys / OAuth / local models
jeo --tmux # run inside an isolated tmux session

Inside the jeo REPL (Tab autocompletes; / opens the palette).

Requirements → plan → approval → execution → verification, carried through .jeo/state/ with real, blocking gates at every handoff:

jeo deep-interview "Describe what you want to build"
jeo ralplan
jeo approve <plan-path>
jeo team
jeo ultragoal

• deep-interview — Socratic loop with ambiguity scoring; freezes a seed only when criteria are concrete (vague-only criteria are refused) and the seed round-trips its own parser. A new idea never silently reuses a completed interview.
• ralplan — drafting passes plus a repo-grounded critic subagent gate: the critic reads the actual repository, must return [OKAY]/[ITERATE]/[REJECT], and the verdict is persisted. Invalid plans (schema, unknown roles) are never marked complete.
• approve — validates the exact contract team executes (schema + roles) and requires the persisted [OKAY] consensus verdict.
• team — serial plan executor with a cross-process run lock, stale-plan reset, per-task subagent contracts, a parent-side mutation audit (a "completed" task with zero observed writes is flagged), and failed-task markers that warn about partial edits on resume.
• ultragoal — honest verification: the suite runs once as a global signal; criteria are recorded, never fabricated as individually passed.

Enable hooks once globally ("hooks": { "enabled": true } in ~/.jeo/config.json), then add a post-edit check per project; the agent sees failures and fixes them before it may call done:

// .jeo/hooks.json
{
 "enabled": true,
 "hooks": [
 { "event": "post-turn", "match": { "tool": "edit|write" }, "run": "bun x tsc --noEmit" }
 ]
}

Non-zero hook output is appended to the tool result the model reads (deduped per batch); a still-red hook triggers a done pushback naming the hook.

ollama pull qwen2.5:0.5b
export JEO_DEFAULT_MODEL=ollama/qwen2.5:0.5b
jeo doctor && jeo

• Global config: ~/.jeo/config.json (model picks are MRU-persisted)
• Project state/sessions: <project>/.jeo/

ANTHROPIC_API_KEY=... OPENAI_API_KEY=... GEMINI_API_KEY=...
JEO_DEFAULT_MODEL=... # e.g. ollama/qwen2.5:0.5b
OLLAMA_HOST=http://localhost:11434
JEO_TUI_THEME=cosmic # cosmic/matrix/solar/red-claw/blue-crab/mono/aurora/synthwave/sakura
JEO_TUI_ALT_SCREEN=1 # legacy alt-screen turn (default: inline scrollback)
JEO_STEP_BASE=24 # dynamic step budget: rolling base
JEO_STEP_HARD_CAP=600 # absolute termination guarantee
JEO_STREAM_MAX_MS=300000 # opt-in overall stream deadline (default off; bounds slow-drip streams)
JEO_TOOL_OUTPUT_MAX=4000 # model-visible tool output cap (full output spills to artifacts)

Retry behavior is tunable via retry in ~/.jeo/config.json (requestMaxRetries, streamMaxRetries, rateLimitRetries, failFastStatuses, ...). The step budget is dynamic by default — it extends while recent tool calls show novel progress and consolidates with a wrap-up when stalled; --max-steps N restores a bounded flow.

CI publishes via .github/workflows/npm-publish.yml — triggered by a published GitHub release, or manually with workflow_dispatch (optional dry-run). The workflow typechecks, tests, verifies the token (npm whoami), then runs npm publish --provenance.

Required npm token permissions (repository secret NPM_TOKEN):

• A Granular Access Token with Read/Write access to the jeo-code package, or a classic Automation token
• "bypass 2FA for publishing" must be allowed — Automation tokens always bypass; granular tokens need the option enabled

• [0.4.4] (2026年06月13日) — Live subagent status mirroring, always-useful Ctrl+O activity tail, read lineRange crash guard.
• [0.4.3] (2026年06月13日) — Readability pass for autopilot, subagent activity, and worked-history review.
• [0.4.2] (2026年06月13日) — Thinking-loop termination guarantees (cycle guard + turn wall-clock budget), unboxed live status without step counters, self-contained .jeo namespace, live next-prompt input card, role-targeted model/thinking picker.
• [0.4.1] (2026年06月12日) — TUI card parity polish + done-time todo reconciliation.
• [0.4.0] (2026年06月12日) — Verified TUI, resilient engine, batch input, multilingual docs.

See CHANGELOG.md for the full history.