Garcon

Run the agents. Steer the work. Ship the change.

Garcon is a self-hosted browser workspace for Claude Code, Codex, Cursor Agent, OpenCode, Amp, Factory Droid, Pi, and your own model endpoints. Keep parallel sessions visible, redirect work while it runs, inspect the real files and diffs, turn pull request feedback into agent tasks, and ship from your computer or phone.

Why Garcon · See it in action · Works with · Quick Start

Different agents, different tasks, one workspace.

Garcon runs on the machine that has your code and uses the agent logins and model endpoints you configure. Agent, terminal, file, and Git operations execute on the Garcon host.

Why Garcon

The terminal is excellent for one focused agent session. It gets harder when several agents are working, one needs approval, another has finished, and the resulting change still needs review. Generic chat interfaces improve visibility but usually stop before the project files, terminal, Git history, and pull request.

Garcon keeps that entire workflow together:

• Run work in parallel. Keep up to four live sessions in resizable split panes, drag chats into place, and see which agents are active, unread, or waiting for you.
• Steer without waiting. Queue the next instruction while an agent is busy, interrupt and redirect the current turn, approve tool use, and answer agent questions in place. Codex sessions can also steer an active turn directly.
• Change approach without losing context. Continue a conversation under another agent or model, fork supported sessions from the full history or an exact message, and compare alternatives side by side.
• Review the work, not just the summary. Browse and edit project files, open a terminal, inspect rendered reasoning and tool calls, review large diffs, and stage individual lines, hunks, files, or folders.
• Close the loop. Read GitHub pull requests and review threads, send a PR or individual comment to the active agent, generate commit messages, commit and push, and manage branches, worktrees, history, and reverts.
• Keep the workload usable. Search and organize chats by project, save filters, tag, pin, rename, reorder, archive, and track what needs attention. Share read-only transcripts and schedule one-off or recurring prompts into new or existing chats.
• Step away without going blind. Use the installable workspace from a phone and receive optional Telegram alerts when work completes, fails, or needs permission.

See It In Action

Steer work while it is still running

Queue the next instruction for later, or interrupt and send it immediately when the plan changes.

Review and ship Inspect the real diff, stage the lines you want, commit, and push.	Unblock work from anywhere Approve a blocked step or reply without going back to your desk.

Built For Agent Work

• Attach images, Markdown, text, and PDF documents, or mention project files with @ autocomplete.
• Read code, Markdown, images, diagrams, agent reasoning, tool calls, and file edits in purpose-built views instead of raw terminal output.
• Follow Codex subagents from one status bar, and use slash-command autocomplete for agent commands, session forks, context compaction, and Codex goals.
• Share a secure, read-only transcript with a teammate or another agent, then revoke it when the work is finished.

Works With

Coding agents: Claude Code, Codex, Cursor Agent, OpenCode, Amp, Factory Droid, and Pi.

Direct model access: Anthropic Messages, OpenAI Responses, and OpenAI Chat Completions compatible endpoints.

Provider presets and discovery: Ollama, OpenRouter, Gemini, Fireworks, Together, Alibaba Cloud, Z.AI, and custom OpenAI or Anthropic compatible services.

Use an existing agent login or subscription where its CLI supports one, or configure API providers in Settings. Each chat keeps its own agent, model, effort, and permission settings where supported.

For CLI-backed agents, Garcon preserves the agent's native history where supported so existing work is not trapped in a separate inbox. Direct API-backed chats live in Garcon and do not have a corresponding CLI session.

Quick Start

git clone https://github.com/cfal/garcon.git
cd garcon
bun run setup
bun run start

Open http://127.0.0.1:8080. On first launch, create an account at /setup, then connect agents and API providers in Settings.

bun run setup installs the root workspace and integration-test dependencies. Authentication is enabled by default.

Requirements

• Bun and git.
• A modern browser: Chrome/Edge 116+, Firefox 124+, or Safari/iOS Safari 17.4+.
• At least one working coding agent or API provider.
• Optional pull request support: an authenticated GitHub CLI on the Garcon host (gh auth login, GHTOKEN, or GITHUBTOKEN). The Pull Requests tab stays hidden when gh is unavailable.

Run And Configure

bun run start --port 8080 --bind-address 127.0.0.1 --project-base-dir /path/to/repos

Useful options and environment variables:

• GARCON_PORT / --port: listen port. Use 0 for a random port.
• GARCONBINDADDRESS / --bind-address: server bind address.
• GARCONCONFIGDIR / --config-dir: base config directory. Defaults to ~/.garcon.
• GARCON_WORKSPACE / --workspace: named workspace under the config directory.
• GARCONWORKSPACEDIR / --workspace-dir: explicit workspace directory.
• GARCONPROJECTBASE_DIR / --project-base-dir: filesystem access boundary.
• GARCONTERMINALSHELL: shell used by terminal sessions.
• CLAUDEBINARY, AMPBINARY, FACTORY_BINARY: override native CLI paths.
• GARCONCODEXCLI: override the Codex CLI used by Garcon.
• GARCONCURSORBINARY: override the Cursor Agent CLI path.
• CURSORAPIKEY: Cursor Agent API key for native Cursor sessions.
• GARCONPIBINARY / PI_BINARY: override the Pi CLI path.
• PICODINGAGENTSESSIONDIR: optional Pi session directory override.

Agent Consultations From The CLI

garcon-cli starts an ordinary Garcon chat through an already-running local server, waits for the submitted turn, and prints the accepted chat and turn IDs before the final assistant response. The same chat remains visible in the SPA, including its tools, permission requests, transcript, and Stop controls.

garcon-cli \
  --workspace default \
  --cwd /path/to/project \
  --agent codex \
  --model gpt-5.4 \
  --permissions acceptEdits \
  --reasoning-effort high \
  --title "Implement validation" \
  "Implement the validation and run its focused tests."

Resume the same agent session without repeating its persisted selection:

garcon-cli --workspace default --resume 1785337200123456 \
  --title "Address review findings" \
  "Now address the review findings."

Query the running server for exact selection values before starting a chat:

garcon-cli list agents
garcon-cli list providers --agent codex
garcon-cli list endpoints --provider local-openai --agent codex
garcon-cli list models --agent codex --provider local-openai
garcon-cli list permissions --agent codex
garcon-cli list reasoning-efforts --agent codex

List commands print compact tables by default and accept --json for scripts and agents. Add repeatable tags with --tag review --tag delegated; every new chat receives the cli tag automatically, and cli records creation through garcon-cli and nothing else. --title sets an explicit title on either a new or resumed chat.

The CLI supports write-capable delegation and does not force plan mode. Permission and reasoning values use the selected agent's live Garcon catalog; inherited bypass modes require the matching explicit --permissions flag. A single - prompt reads stdin. Use -- before a positional prompt whose first word is list, send-async, stop, status, or wait. Interrupting the terminal detaches the CLI without stopping work in Garcon.

Every accepted start or resume prints an exact handle before waiting:

chat id: 1785337200123456
turn id: 7fc16cb7-53e0-4c10-a4a4-cd85900eb548

Retain both values to reattach after a terminal interruption without submitting the prompt again:

garcon-cli --workspace default wait 1785337200123456 \
  --turn 7fc16cb7-53e0-4c10-a4a4-cd85900eb548

wait --json prints the terminal turn receipt as one JSON document. Turn receipts belong to the running server process and may expire under retention pressure, so reattachment can fail after a server restart or receipt eviction even though the chat transcript remains available in Garcon.

Inspect current chat-level progress when no retained turn handle is available:

garcon-cli --workspace default status 1785337200123456
garcon-cli --workspace default status 1785337200123456 --messages 20 --json

status returns the current processing phase, execution control, pending inputs, and the latest 10 normalized transcript messages by default. --messages accepts 0 through 200; zero skips transcript loading for a lightweight execution-state check. A temporarily unavailable transcript is reported inside an otherwise successful snapshot. JSON is the stable machine-readable interface; plain text redacts image bodies and truncates each message at 4,000 characters.

Status is a one-shot, non-transactional chat observation. status: idle does not prove that a particular turn settled or that a just-finished message batch is already visible. Use wait with the exact accepted chat and turn IDs when completion identity matters, especially before retrying write-capable delegated work.

One-Shot Chat Control From The CLI

send-async submits one turn to an existing chat and returns immediately after Garcon accepts it, without waiting for the agent to finish. The turn runs in Garcon and stays fully visible and stoppable in the SPA. It inherits the chat's saved execution settings, so it may edit files or run tools when the chat permits them; it accepts no model, permission, or other execution overrides.

garcon-cli --workspace default send-async 1785337200123456 \
  "Implement the reviewed changes and run the focused tests."

chat id: 1785337200123456
delivery: new-turn
turn id: 7fc16cb7-53e0-4c10-a4a4-cd85900eb548

If the chat is busy running another turn, send-async reports the busy state and exits 3 without queueing or steering. Pass --allow-steer to deliver the message into the active turn instead; --allow-steer never queues:

garcon-cli --workspace default send-async 1785337200123456 \
  --allow-steer "Also update the migration test."

chat id: 1785337200123456
delivery: steer
turn id: 7fc16cb7-53e0-4c10-a4a4-cd85900eb548

When the chat state changes between the run and steer checks, send-async alternates between the two endpoints for at most three total attempts with a short delay, then reports the race instead of risking a duplicate delivery. Use a single - as the message to read UTF-8 text from stdin:

printf '%s' "Apply the patch described in /tmp/review.md" | \
  garcon-cli --workspace default send-async 1785337200123456 --allow-steer -

stop interrupts the active turn through the same REST command the SPA Stop button uses, and treats an already-idle chat as success. If queued messages exist, stopping pauses the queue so they do not start after the interruption; resume the queue in Garcon before sending a new direct turn:

garcon-cli --workspace default stop 1785337200123456

chat id: 1785337200123456
stop: interrupt-requested

Ctrl-C detaches the terminal without sending stop; interrupting a send-async or stop invocation reports that the command may have reached Garcon, so inspect the chat before retrying. Neither send-async nor stop adds the cli tag; only starting a chat through garcon-cli does.

Discovery requires the server to use a named --workspace; servers launched with --workspace-dir are intentionally not discoverable. --server may assert the descriptor's exact URL but cannot redirect credentials to another listener. Run garcon-cli --help for provider, endpoint, and complete mode options.

Local Trusted Use

To disable Garcon's local authentication for a trusted single-user environment:

bun run start --disable-auth
or
GARCONDISABLEAUTH=true bun run start

Do not expose an unauthenticated instance to an untrusted network. API keys are stored on the Garcon server and redacted from client responses, but configured agents and model providers still receive the context required to perform their work. Review the security notes, including the WebSocket token logging considerations, before exposing Garcon beyond a trusted network.

Build And Develop

bun run build      # Build the SvelteKit frontend
bun run build-exe  # Build and smoke-test standalone executables
bun run check      # Lint and type-check
bun run test       # Run server, protocol integration, and web tests

Integration Tests

integration-tests/ starts a real Garcon server in an isolated temporary workspace and drives it through public HTTP and WebSocket contracts. A deterministic fake OpenAI-compatible server covers direct-chat lifecycle, queueing, interrupt delivery, reconnect and transcript stability, persistence, deletion, forking, concurrent chats, and provider failures without external credentials.

bun run test:integration:server
bun run build
LIGHTPANDA_BIN=/path/to/lightpanda bun run test:integration:e2e

The Lightpanda suite reuses the same process fixture and fake provider to exercise the production SPA without graphical screenshot assertions. CI pins and verifies the Lightpanda binary; local runs require LIGHTPANDA_BIN to name an executable binary.

Future integration coverage should add credential-backed, non-blocking validation for Claude Code, Codex, Pi, Cursor Agent, OpenCode, Amp, Factory Droid, and other supported agents; real OpenAI, Anthropic, and provider-preset APIs; agent-native transcript, permission, tool, compaction, and subprocess behavior; authentication; partial assistant-token reconnects; and a graphical Chromium/WebKit lane for layout, screenshot, and accessibility rendering checks. External canaries must remain separate from deterministic correctness gates because they are costly and nondeterministic.

Repository layout:

• web/: SvelteKit and Svelte 5 frontend.
• server/: Bun HTTP/WebSocket server, agents, providers, queueing, Git, auth, and notifications.
• common/: shared chat, transport, agent, provider, model, settings, and API contracts.
• integration-tests/: black-box server and Lightpanda SPA integration suites.