cute-code

A terminal coding agent with a local browser UI, multi-provider model support, and worktree-aware sessions.

Use it as a REPL, a one-shot CLI, or a browser-managed local session. It supports Anthropic models, GPT/Codex-style models, Codex Pool-backed servers, custom model definitions, MCP, voice input, and browser-side session management.

curl -fsSL https://git.irrigate.cc/pp/cute-code/raw/branch/main/install.sh | bash

What it does

cute-code is a coding agent for local development work. You can run it directly in the terminal, open the same runtime in a browser UI, point it at Anthropic or OpenAI-compatible model stacks, and keep separate tasks isolated in their own worktrees.

The useful part is not one headline feature. It is the combination:

• terminal REPL and one-shot prompt mode
• browser UI backed by a local daemon
• Anthropic, GPT/Codex-style, and custom registered models
• MCP support
• worktree-per-session workflows
• voice mode and OpenAI-backed image generation
• broader agent/runtime features like planning, monitoring, and autodrive

Why people use it

Capability	Why it matters
Multi-provider model support	Run Anthropic models, GPT/Codex-style models, Codex Pool-backed servers, and custom registered models from one client.
Better OpenAI integration	GPT-family sessions include deeper runtime support such as native web search, remote compaction, Codex config loading, Codex Pool login flows, smarter agent model mapping, and mid-turn narration.
Browser session management	The browser UI supports persistent transcripts, pinned and renamed sessions, attachments, inline generated images, and better session controls than a single terminal pane.
Worktree workflows	Start isolated sessions in separate worktrees so parallel tasks do not fight over one branch.
Local tool surface	MCP, image generation, voice mode, and computer-use support can live inside the same runtime.
Better release ergonomics	Cross-platform binaries, install scripts, compiled web assets, and Gitea releases make it usable as software, not just as a source tree.

Quick start

Install

macOS / Linux:

curl -fsSL https://git.irrigate.cc/pp/cute-code/raw/branch/main/install.sh | bash

Windows PowerShell:

irm https://git.irrigate.cc/pp/cute-code/raw/branch/main/install.ps1 | iex

Or download a binary from the releases page.

Nix profile (x86_64 Linux)

On an x86_64 Linux machine with Nix, the flake can install cute-code into your user profile without root access:

nix profile add "git+https://git.irrigate.cc/pp/cute-code.git?ref=main#cute-code"

Run it with cute-code. To rebuild from the latest main revision later, run:

nix profile upgrade --refresh cute-code

From a checkout, nix run . builds and runs the current branch in an isolated Nix store path. nix develop opens the pinned Bun development shell; with direnv installed, approve it once with direnv allow and it will load automatically when entering the checkout.

Start a terminal session

For Anthropic models:

export ANTHROPIC_API_KEY="sk-ant-..."
cute-code

For GPT/Codex-style models:

export OPENAI_API_KEY="sk-..."
cute-code --model gpt-5.6

If you prefer interactive login:

cute-code /login

The login flow also supports Codex Pool. The Codex Pool path saves pooled Anthropic and OpenAI credentials, then refreshes the server's model catalog automatically.

Run a one-shot task

cute-code -p "explain the architecture of this repository"

Launch the browser UI

cute-code web

When developing the browser UI from a source checkout, start it with Vite hot reload:

bun run dev -- web --hot

If no daemon is running, this starts the daemon on port 1847 and Vite on port 1848. If cute-code web is already running on the requested daemon port, the command automatically attaches only Vite to that daemon, preserving its active agents and sessions. Frontend source edits then update through Vite automatically.

When the source command started both processes, cute-code web reload relaunches only its supervised frontend. When it attached to a separately started daemon, stop and rerun the source command after Vite configuration or dependency changes; stopping it leaves the daemon untouched.

If you want to expose that local web session through the relay:

cute-code web --share

Treat share mode as remote shell access. Anyone with the passcode can act as you.

Core capabilities

Provider and model support

cute-code can run against Anthropic models, GPT/Codex-style models, Codex Pool-backed servers, and custom model definitions you register in settings. The current runtime also includes extra OpenAI-side work that simple compatibility layers usually skip: Codex config loading, native web search routing, remote compaction, better long-session handling, GPT-oriented mid-turn narration, and a dedicated Codex Pool login flow that configures credentials and refreshes pool-defined models.

Browser sessions

cute-code web starts a local daemon and opens a browser UI for the same runtime. That UI supports persistent transcripts, pinned sessions, auto-titles, rename/delete flows, slash-command discovery, attachments via drag-and-drop or paste, and inline rendering for generated images.

Worktree-based workflows

cute-code can create isolated sessions in separate worktrees so you can run several coding threads at once without stomping on the same working tree. The browser-side flow also supports inspecting and publishing worktree sessions.

Advanced agent workflows

Beyond the base prompt loop, the runtime includes planning and verification flows, autodrive, and the Monitor tool for streaming background shell events. If you use cute-code for longer-running work instead of one prompt at a time, those additions matter.

Band peer workflow

Band peer behavior is available as a first-party runtime feature. Use /band enable or /band disable to turn passive Band processing on or off without deleting profiles, peers, queues, or archives. /band status, /band inbox, /band reply, and /band ack expose the durable Band queue in the terminal, while the browser UI uses the same local service layer for peers, chats, send, reply, and ack controls.

Existing Jam users can run /band migrate for a dry-run report against $JAM_CONFIG_DIR or Jam's default config directory. Re-run with /band migrate --import to copy validated profiles, peer sessions, queues, and archives into cute-code's Band state. See docs/band-peer/migration.md for the safe migration path and the Jam surfaces that remain out of scope for first-party v1.

Local tools

The local tool surface includes MCP integration, voice mode, OpenAI-backed image generation, and computer-use support where the platform and runtime support it. In the current implementation, image generation goes through OpenAI auth, either via API key or ChatGPT/Codex-style auth.

Common commands

Command	What it does
cute-code	Start the interactive terminal session.
cute-code -p "..."	Run a one-shot prompt and exit.
cute-code --model gpt-5.6	Start with a specific model.
cute-code web	Launch the local browser UI.
bun run dev -- web --hot	Launch Vite on port 1848, starting a daemon or attaching to the existing one on port 1847.
cute-code web reload	Relaunch the hot frontend when the source command owns both daemon and frontend.
cute-code web --share	Launch the browser UI and expose it through the share relay.
cute-code --version	Print the current version.

Inside the REPL, you also have slash commands for model switching, login, permissions, skills, session controls, voice mode, planning flows, and background-task workflows.

Source lint policy

Biome checks handwritten source with its recommended rules. In mixed React compiler output, declaration-level noImplicitAnyLet suppressions identify compiler temporaries restored from memo-cache slots. Other declarations and rules remain checked. The imported source already contains the compiler transform; this repository does not run a pre-transform lint stage.

The biome.json linter override lists four imported protobuf outputs explicitly:

• src/types/generated/events_mono/claude_code/v1/claude_code_internal_event.ts
• src/types/generated/events_mono/common/v1/auth.ts
• src/types/generated/events_mono/growthbook/v1/growthbook_experiment_event.ts
• src/types/generated/google/protobuf/timestamp.ts

Their headers identify protoc-gen-ts_proto v2.6.1 and the original schema paths. The upstream portable baseline supplies these outputs; its maintainers retain schema and generator ownership. This checkout contains no regeneration command or owning schemas. Update these files from that baseline rather than editing generator output to satisfy source lint rules. Formatting still checks them.

Configuration

cute-code reads settings from ~/.claude/settings.json.

Example:

{
  "model": "gpt-5.6",
  "openaiApiKey": "sk-...",
  "openaiBaseUrl": "https://gateway.example.com/v1",
  "anthropicApiKey": "sk-ant-...",
  "anthropicBaseUrl": "https://api.anthropic.com",
  "maxConcurrentWorkflowAgents": 12,
  "customModels": [
    {
      "id": "gateway/o3",
      "name": "o3 via gateway",
      "protocol": "openai",
      "baseUrl": "https://gateway.example.com/v1",
      "contextWindow": 200000,
      "description": "OpenAI-compatible model exposed through an internal gateway"
    },
    {
      "id": "gateway/opus-like",
      "name": "Opus-like internal model",
      "protocol": "anthropic",
      "baseUrl": "https://anthropic-gateway.example.com",
      "contextWindow": 200000
    }
  ]
}

Useful settings surfaced by the current schema include:

• openaiApiKey and openaiBaseUrl
• anthropicApiKey and anthropicBaseUrl
• customModels for Anthropic- or OpenAI-protocol backends
• maxConcurrentWorkflowAgents to raise or lower the number of workflow subagents that can run at once (integer 1 through 64; it overrides the default CPU-aware cap and the default four-agent per-workflow cap)
• the usual model, permissions, environment, and session settings

If you already use Codex, cute-code can also read Codex auth/config and pick up provider base URL information from there on the OpenAI side. If you use a Codex Pool server, the login flow writes pooled Anthropic/OpenAI credentials and caches the pool's authenticated model catalog without copying credentials into each model entry.

Architecture at a glance

                    +----------------------+
                    |      cute-code       |
                    |  REPL / one-shot     |
                    +----------+-----------+
                               |
              +----------------+----------------+
              |                                 |
      +-------v--------+                +-------v--------+
      | local runtime  |                | browser daemon |
      | bash/read/edit |                | web sessions   |
      | MCP/image/voice|                | transcripts    |
      | monitor/agents |                | attachments    |
      +-------+--------+                | worktrees      |
              |                         +-------+--------+
              |                                 |
              +----------------+----------------+
                               |
                    +----------v-----------+
                    | model + API layer    |
                    | Anthropic            |
                    | OpenAI / Codex       |
                    | custom endpoints     |
                    +----------------------+

Build from source

cute-code builds with Bun >= 1.4.2.

bun install
bun run build
./cli

Useful development commands:

bun run dev
bun run build:dev
bun run build:dev:full
bun test -- src/query.test.ts
bun run release:build

For the source-check baseline, install both dependency sets, then run:

bun install --frozen-lockfile
bun install --cwd web --frozen-lockfile
bun run check

check runs the root and web TypeScript compilers, the representative src/query.test.ts suite, and the SDK protocol check. Pull-request CI runs this same baseline, both process-runtime suites below, and a production CLI build.

bun test -- src/runtime/processSessionRuntime.test.ts
bun test -- src/webui/server/localSessionController.processRuntime.test.ts

These integration suites compile a temporary development binary from the current checkout, including the process-runtime feature, and remove it afterward. They use disposable profiles and a local provider fixture; an existing cli-dev is not required. Building the child also builds and embeds the browser assets.

bun run lint and bun run format:check check source under src, web, scripts, and packages/agent-sdk. Biome excludes dependency/vendor directories, web/dist, embedded browser assets, generated tree-sitter grammars, and generated SDK core types. Handwritten SDK code remains included. Existing repository-wide lint and formatting diagnostics remain unresolved, so these commands and the separate CI style job currently fail. bun run check:full adds those checks and bun run test to the baseline, stopping at the first failure.

bun run test invokes the full colocated Bun suite, beyond the representative baseline. Browser interactions, release-packaged binaries, voice hardware, and live-provider authentication require separate checks in their supported environments. The temporary-worker tests do not establish those results.

Troubleshooting

ANTHROPIC_API_KEY is not set

Set an Anthropic API key before starting a session:

export ANTHROPIC_API_KEY="sk-ant-..."

OPENAI_API_KEY is not set

Set an OpenAI API key before using GPT or Codex-style models:

export OPENAI_API_KEY="sk-..."

The binary installed but cute-code is not found

Make sure your install directory is on PATH.

On macOS and Linux the default install path is:

~/.local/bin

On Windows it is:

$env:LOCALAPPDATA\Programs\cute-code\bin

cute-code web starts but I cannot connect

By default the web UI listens locally. If you need access from another machine, use share mode intentionally:

cute-code web --share

Voice mode does not work

Voice support depends on local audio capture support and a usable microphone environment. If your machine does not expose audio capture correctly, the rest of the app still works normally.

Limitations

• Building from source requires Bun.
• Tests are colocated with the source and run with Bun, for example bun test -- src/query.test.ts. The suite is incomplete; browser, packaged-runtime, voice, provider, and credential-dependent behavior still require their supported environments.
• Some features depend on the local environment, especially voice and computer-use support.
• Share mode is powerful and should be treated carefully because it exposes agent access to your machine.

FAQ

Can I use Anthropic and OpenAI models in the same tool?

Yes. cute-code supports both stacks and also supports custom model registrations in settings.

Is the OpenAI support just basic API compatibility?

No. The runtime includes dedicated OpenAI translation, model handling, auth/config loading, remote compaction, native web search routing, and mid-turn narration for GPT-family sessions.

Does it work with Codex Pool servers?

Yes. The login flow includes a Codex Pool path that claims pooled credentials from a server URL plus friend code, writes both Anthropic and OpenAI base URLs/API keys, and refreshes the authenticated pool model catalog.

Can I point it at a proxy, pool, or internal gateway?

Yes. The settings schema includes both Anthropic and OpenAI base URL overrides, plus custom model definitions.

Does it support MCP?

Yes. MCP servers are part of the core workflow.

Can I ignore the browser UI and stay in the terminal?

Yes. The terminal REPL remains the primary experience. The browser UI is there when you want uploads, persistent transcripts, session management, or worktree flows.

Can it isolate sessions in separate worktrees?

Yes. The current codebase supports worktree-aware sessions and publish flows around them.

About Contributions

Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via gh and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.

License

See LICENSE if present in your checkout, and review the repository metadata on the host you downloaded it from.