CYCode

General coding agents stop at code. Research is code plus literature, experiments, notebooks, and papers — so CYCode makes them first-class tools, not afterthoughts:

• 📚 Papers — arxiv_search, paper_read (PDF → text, page ranges), semantic_scholar (search + references). /lit-review produces structured notes with BibTeX — every citation comes from a real tool result, never from model memory.
• 🧪 Experiments — exp_run launches training scripts detached in the background; exp_status tails logs, extracts metrics by regex, and reads local wandb runs' summary metrics (offline, no API key); /watch-run reports trends and flags divergence (NaN losses, OOM, frozen output).
• 📓 Notebooks — notebook_read / notebook_edit operate on .ipynb cells directly, preserving nbformat.
• 📄 LaTeX — latex_build compiles via latexmk/pdflatex and returns structured file:line errors. /paper-draft writes grounded in your actual results.
• 💻 Code — the full coding toolkit: read, write, edit, glob, grep, bash, web_fetch (plus optional web_search), with permission gating on everything and post-edit diagnostics fed back to the model.
• 🔁 Loops — cycode exec "task" --json emits machine-readable events and meaningful exit codes, designed to be driven by recurring agent loops, cron, and CI.

Heritage

CYCode is a lean harness (~5K lines of strict TypeScript) written from scratch, deliberately combining the best ideas of the three major agent lineages. All code is original; no proprietary source was used.

Install

Download a standalone binary — no Node required — from the latest release:

tar xzf cycode-darwin-arm64.tar.gz && mv cycode-darwin-arm64 /usr/local/bin/cycode
cycode --version

Or build from source (Node ≥ 20):

git clone https://github.com/ChaoYue0307/CYCode && cd CYCode
npm install && npm run build && npm link    # then: cycode

Then get set up in two commands:

cycode init      # scaffold .cycode/config.json + AGENTS.md (detects your keys)
cycode doctor    # check keys, git, sandbox, and optional tools

Optional extras used when present: rg (faster grep), latexmk, jupyter. (npm registry publication is planned.)

Quickstart

export ANTHROPIC_API_KEY=...   # or OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY / OPENROUTER_API_KEY
cd your-project

cycode                          # interactive terminal REPL
cycode ui                       # local web GUI at http://127.0.0.1:7833
cycode -c                       # continue the most recent session
cycode exec "run the test suite and fix any failures" --mode acceptEdits
cycode exec "/watch-run" --json # headless skill run with JSONL event output

In the REPL: /help, /mode, /compact, /skills, esc interrupts, and any /skill-name runs a skill.

Three interfaces, one agent

The agent core emits events through a bus and asks for permissions through an arbiter interface — so every frontend gets identical behavior and the same security model.

Models

Specify models as provider/model-id — switch providers without changing anything else:

cycode --model anthropic/claude-sonnet-4-6
cycode --model openai/gpt-5.1
cycode --model google/gemini-2.5-pro
cycode --model deepseek/deepseek-chat       # Chinese providers are built in…
cycode --model qwen/qwen-max                 # …Qwen, Zhipu/GLM, Kimi, Doubao, ERNIE,
cycode --model zhipu/glm-4.6                 #    Hunyuan, MiniMax, SiliconFlow, StepFun…
cycode --model ollama/llama3.3              # local, via http://localhost:11434/v1
cycode --model openrouter/anthropic/claude-sonnet-4-6

Built-in providers: Anthropic, OpenAI, Google, OpenRouter, Ollama, and the major Chinese providers — DeepSeek, Alibaba Qwen, Zhipu GLM, Moonshot Kimi, MiniMax, Tencent Hunyuan, ByteDance Doubao, Baidu ERNIE, SiliconFlow, StepFun, Baichuan, 01.AI Yi — with endpoints baked in (just set a key). Full table in docs/configuration.md.

Every provider takes its API key from either an environment variable or the config file — set ANTHROPIC_API_KEY / OPENAI_API_KEY / GOOGLE_GENERATIVE_AI_API_KEY / OPENROUTER_API_KEY, or put the key under providers.<name>.apiKey in ~/.cycode/config.json. Any OpenAI-compatible endpoint (vLLM, llama.cpp server, litellm proxy) can be added under providers too — handy for evaluating your own fine-tuned models as coding agents. See docs/configuration.md.

Permissions

Read-only tools run freely; everything else passes a gate before executing. Four modes: default (ask), acceptEdits (file edits auto-approved, commands still ask), plan (read-only), bypass (everything approved — use with care).

Allow/deny rules use Claude Code-style patterns, and "always allow" answers persist per-project:

// .cycode/config.json
{
  "permissions": {
    "allow": ["bash(git *)", "bash(npm run *)", "latex_build"],
    "deny":  ["bash(rm -rf *)"]
  }
}

Deny rules win over everything — including read-only tools and bypass mode. Two more layers stack on top:

• Hooks — shell commands before/after tool calls that can block them deterministically (exit 2), e.g. forbid force-pushes no matter what the model decides.
• Sandbox (--sandbox) — kernel-level confinement of shell commands to the project dir + tmp (macOS Seatbelt / Linux bubblewrap, fail-closed). cycode exec "..." --mode bypass --sandbox is full autonomy inside a write-fence.

Full grammar, hook contract, and sandbox details in docs/configuration.md.

Skills

Skills are markdown prompts with YAML frontmatter (the same shape Claude Code uses), loaded from the package, ~/.cycode/skills/, and <project>/.cycode/skills/ — later sources override earlier ones. Invoke with /name args.

Built-ins: /lit-review · /watch-run · /paper-draft · /repro-check — see docs/skills.md for the format and a writing guide.

Undo anything

CYCode snapshots the workspace before every turn into a shadow git repo (never touching your project's .git), so you can let it edit freely and roll back:

cycode diff      # what did the last turn change?
cycode undo      # revert the workspace to before the last turn

/undo, /diff, and /checkpoints work inside the REPL too. Undo touches only the files that actually changed — modified/deleted files are restored, added files removed, everything else untouched. On by default; needs git. See docs.

Sessions

Every interactive session is an append-only JSONL rollout under ~/.cycode/sessions/<project>/ — kill the terminal mid-task and cycode -c picks up exactly where it left off. Long conversations auto-compact at ~80% of the context window. cycode sessions lists history; --resume <id> reopens any of them.

Driving CYCode from a loop

# process a task list, one isolated agent run per line
while read -r task; do
  cycode exec "$task" --mode acceptEdits --json >> runs.jsonl || echo "FAILED: $task"
done < tasks.txt

Each JSON line is an agent event (tool-start, text-end, turn-end, …) ending with {"type":"result","text":…,"exitCode":…} — everything a supervising loop needs to verify, retry, or escalate. Event schema and loop patterns: docs/loops.md.

How CYCode compares

CYCode doesn't try to beat the big harnesses at general software engineering — it trades breadth for a sharp research focus and a codebase small enough to fully understand, audit, and modify.

Roadmap

• Standalone binaries for macOS / Linux / Windows (GitHub Releases)
• Hooks (pre/post tool-use shell guardrails)
• Parallel execution of read-only tool batches (incl. explore fan-out)
• Runtime model switching (/model) and session token tracking
• OS-level bash sandboxing (macOS Seatbelt / Linux bubblewrap, --sandbox)
• wandb local-run metrics in exp_status (offline, no API key)
• Eval harness — verifiable task benchmark with a pass-rate
• Built-in Chinese providers (DeepSeek, Qwen, GLM, Kimi, Doubao, ERNIE, …)
• Trust layer — per-turn git checkpoints with undo / diff
• cycode init / cycode doctor onboarding
• Reliability — multi_edit, line-ending-tolerant edits, configurable retries
• Vision/multimodal input (read plots, figures, architecture diagrams)
• npm package release (npm i -g cycode)
• Native desktop app (Tauri) wrapping the GUI
• TensorBoard event-file metrics in exp_status
• LSP-based diagnostics (currently command-based)

Have an idea? Open an issue.

FAQ

Why not just use Claude Code / Codex / OpenCode? Use them! CYCode exists for researchers who want paper/experiment/notebook/LaTeX tools built in, model freedom for agent research, and a harness small enough to hack on — and for anyone who wants to understand how coding agents work by reading one.

Does it send my code anywhere? Only to the model provider you configure. Sessions, logs, and paper caches stay on disk under ~/.cycode/. The web GUI binds to 127.0.0.1 and is never exposed to the network.

Can I use it with my own fine-tuned model? Yes — point a providers entry at any OpenAI-compatible server (vLLM, llama.cpp, litellm) and pass --model yourname/your-model.

Is it safe to run unattended? exec denies anything not pre-approved by mode or allow-rules instead of prompting. Start with --mode acceptEdits plus explicit bash(...) allow rules; treat bypass as a sandbox-only mode.

Development

npm install
npm run dev          # tsx src/cli.ts
npm test             # vitest — 51 tests, no API key needed (mock model)
npm run typecheck && npm run lint && npm run build

Evals — a small benchmark drives the real agent against verifiable tasks so changes can be judged by a pass-rate, not a vibe: npm run eval (see docs/evals.md).

Contributions welcome — see CONTRIBUTING.md. Security reports: SECURITY.md.

Acknowledgments

CYCode stands on ideas from Claude Code (Anthropic), Codex CLI (OpenAI), and OpenCode (SST). Built with the Vercel AI SDK, Ink, and the MCP SDK.

License

MIT © ChaoYue0307