jeo-code

<p align="center" <img src="assets/hero.png" alt="jeo-code autonomous coding-agent hero illustration" width="100%" / </p

<h1 align="center"jeo-code (jeo)</h1

<p align="center" <strongEncode intention. Decode software.</strong<br / A Bun-based AI coding-agent CLI — interviews, reviewed plans, gated execution, honest verification. </p

<p align="center" <a href="https://github.com/akillness/jeo-code"<img alt="license" src="https://img.shields.io/badge/license-MIT-green?style=flat-square"</a <img alt="runtime" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.3.14-f9f1e1?style=flat-square&logo=bun&logoColor=black" <img alt="zero native deps" src="https://img.shields.io/badge/native%20deps-0-blue?style=flat-square" </p

<p align="center" <img src="assets/character.gif" alt="animated jeo-code red crayfish mascot smart-routing a prompt to the cheapest provider and saving coins" width="320" / <img src="assets/character-v2.png" alt="jeo-code red crayfish mascot piloting the computer-use desktop-automation control panel while juggling prompt-routing provider nodes" width="320" / </p

<p align="center" <bEnglish</b · <a href="README.ko.md"한국어</a · <a href="README.ja.md"日本語</a · <a href="README.zh.md"中文</a </p

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.

Documentation

📖 Usage guide — install, TUI controls (↑ recall, Ctrl+O, ! shell), slash commands, /resume, and the spec-first workflow, with a demo video.

<video src="https://raw.githubusercontent.com/akillness/jeo-code/main/docs/jeo-code-promo.mp4" controls muted playsinline width="100%"</video

Demo not playing inline? ▶ Play / download the demo video.

Highlights

• Prompt routing (cost-aware, credential-aware) — every turn can auto-route to a tier-appropriate model among only the providers your configured credentials actually serve (/route [status|on|off|why|history]), with a live equivalent-model fallback whenever a routed provider is rate-limited, unauthenticated, unreachable, or silently times out — see /route why for the last decision, /route history for the recent ones.
• Computer use (desktop automation) — a fail-closed computer tool (screenshot/click/type/scroll/drag/batch) gated by both a config flag and an independent kill-switch/heartbeat supervisor; toggle it for the current session with /computer [status|on|off] without touching ~/.jeo/config.json.
• Multi-provider, one loop — Anthropic / OpenAI (+Codex) / Gemini / Antigravity / Ollama / LM Studio, plus 20+ OpenAI- and Anthropic-compatible clouds (Groq, DeepSeek, Mistral, OpenRouter, xAI, Kimi, z.ai, …), all behind one uniform JSON tool loop. OAuth login happens from the input box (/provider login), every model pick persists as the new default, and prompt routing only auto-selects usable credentialed paths: Gemini OAuth goes through the provider-qualified antigravity/ agent set (Gemini 3.5 Flash tiers, Gemini 3.1 Pro, Claude Sonnet/Opus 4.6), never public google/gemini- rows that require GEMINIAPIKEY; if a configured route points at an unready provider, jeo switches to an equivalent credentialed tier model before falling back to the 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.

• Browser tool — headless Chromium automation (Playwright) as a first-class agent tool: open/close/run/act on named, reused tabs, with observe-tagged element ids preferred over screenshots for driving pages. act {verb:"verify", goal, ...} closes the visual-QA loop: screenshots the page and asks an independent vision-capable model to judge it against a plain-language goal ({verdict:"PASS"|"MISMATCH", detail}) instead of requiring a human (or the same agent) to eyeball a saved PNG. Requires npx playwright install chromium once (not bundled — jeo stays zero native deps itself, the browser binary is Playwright's separate download).
• Skills that compound — a stalled turn now writes the dead end into the SAME skill's project-level file (.jeo/skills/<name.md, seeded from the bundled skill on first write, deterministic keyword match, no LLM), so the next session's $<skill invocation carries accumulated "Known Failure Modes"/"Anti-Patterns" knowledge instead of the bundled doc staying static forever. jeo skills lesson <skill <failure|anti-pattern "<title" "<detail" for manual entries; jeo skills eval <skill runs a real LLM judgment on whether each recorded lesson is still covered by the skill's current guidance or has gone stale.
• Cheap-tier grader routing — the /goal verifier, the critic subagent role, and unpinned task fan-out batches default to a cheap credentialed model instead of silently riding the same full-price model as the work they're grading/executing (resolveVerifierModel, vision-capability-filtered for the browser verify action so a text-only cheap model never silently drops an attached screenshot).
• jeo routine init — generates a GitHub Actions workflow that runs jeo headlessly (jeo "<prompt" -p) on a schedule/issue/PR trigger, on GitHub's own runners — no laptop required, and zero new attack surface inside jeo itself (no in-process scheduler or webhook listener). --dry-run to preview, --no-pr for a direct commit instead of the default PR-per-run.
• Remote subagent visibility (Telegram) — pair a bot once (jeo notify setup), then jeo daemon start pushes a message on every subagent state edge (started → done/failed/cancelled) and accepts /subagents, /steer <id <subagentId <msg, /cancel <id <subagentId back. Telegram Daemon now supports full gjc parity, including forum topics, inline keyboards, and image attachments — commands are authorized to the paired chat only.
• Independent verifier, actually enforced — a plan can no longer skip its architect/critic step: PlanSchema rejects any plan that ends with an unverified mutation (a verifier placed BEFORE the mutation it should check doesn't count either), at both ralplan draft time and team/approve execution time. Every architect/critic verdict must also show real evidence — zero observed read/search/find/astgrep/lsp calls blocks the verdict regardless of what the text claims.

• Safety-boundary automatic model fallback — an uncategorized safety refusal (a possible classifier false positive, not a genuine content-policy hit) now switches to a genuinely different-provider model instead of backing off forever on the same one — mirrors the existing rate-limit fast-fallback. A Refusal (<category)-shaped deterministic hit is untouched and still hard-fails with zero fallback.
• Memory: earned confidence — a concept's verification date is now written only when a distillation pass is explicitly marked verified, not on every write; isConceptStale treats an unverified (or 30-day-stale) concept as needing re-verification instead of trusting a passive timestamp.
• Dynamic Workflows (eval tool) — write real JS control flow around subagent dispatch: task(role, taskText, context?), parallel(thunks), pipeline(items, ...stages), and log(message), composing sequential/branching orchestration that task's single-stage tasks[] batch can't express. Runs in an isolated Worker thread with a genuinely preemptive timeout (worker.terminate(), not a same-process race) — same full-process trust as bash, no sandbox pretense, gated by the same interview mutation lock.
• Quiet exit on a broken output pipe — piping jeo into a command that stops reading early (jeo --help | head, a vanished remote peer) no longer dumps a raw EPIPE stack; it exits quietly with the same code (141) a shell reports for any SIGPIPE-killed pipeline producer. A genuine crash is unaffected and still surfaces clearly.
• macOS low file-descriptor-limit warning — a low ulimit -n (BSD's 256/1024 default) risks opaque EMFILE failures from file watching, the browser tool, or a broad repo scan; jeo now warns once at launch (stderr only, never piped -p output) with concrete ulimit/launchctl guidance. Opt out with JEOSKIPNOFILECHECK=1.

Install

Requires Bun 1.3.14+.