garcon

Garcon

Run the agents. See the work. Ship the change.

Garcon is a self-hosted visual workspace for coding agents. Run Claude Code, Codex, Cursor Agent, OpenCode, Amp, Factory Droid, and Pi side by side, coordinate their work, and move from prompt to reviewed commit without leaving the browser.

Quick Start · Why Garcon · See It In Action · Automate And Delegate

Keep delegated results, chat lineage, files, terminals, and Git visible in one resizable workspace.

Garcon runs agents, terminals, files, Git, and pull request commands on the host under your account, using the agent logins and model endpoints you configure.

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. Authentication is enabled by default.

Requirements:

• Bun, git, and a modern browser.
• At least one working coding agent or API provider.
• Optional pull request support: an authenticated GitHub CLI on the selected executor, with support for gh auth status --json hosts and gh api --paginate --slurp.

Garcon publishes an official multi-platform container image for every commit on main:

docker pull ghcr.io/cfal/garcon:main

The Docker guide covers running the published image, building the current checkout, image tags, volumes, agent login, Git, SSH, and toolchains.

Starting with v0.4.0, GitHub releases include server/CLI archives, source, checksums, provenance, and explicitly labeled native previews. Native previews are not signed production distributions; Android connections remain disabled and iOS is simulator-only. Human publication starts Docker promotion to the exact version tag and, for the current stable release, latest. See release verification and operations.

Why Garcon

One agent chat is easy. The hard part begins when several agents are running, one needs approval, another has finished, and their changes still need to be understood and shipped.

Garcon keeps that development loop coherent:

• Orchestrate visually. Tile up to four resizable windows, move local tabs between them, organize live chats on durable canvases, track work on tag-driven boards, and inspect fork, handoff, and delegation lineage in Chat Map.
• Stay in control of every turn. Queue and reorder instructions, steer active work, approve tools, answer agent questions, pause the queue, interrupt, or stop without losing the transcript.
• Coordinate agents visibly. Exchange provenance-labeled messages between chats, launch delegated children, receive their final results, and keep parentage auditable instead of hiding it in a side channel.
• Track durable work. Create workspace tickets in a list or status board, assign and claim work, discuss progress, and retain attributed change history across chat deletion and server restarts.
• Review the real change. Browse and edit files, run terminals, inspect reasoning and tool calls, review diffs, then stage individual lines, hunks, files, or folders before committing and pushing.
• Find and reuse context. Search chat metadata and indexed transcripts, save filters, tag, pin, archive, export Markdown or XML, build bounded handoffs, share snapshots, and schedule prompts with per-prompt pause and resume.
• Know what agents cost. See token usage and estimated API cost per day, agent, and model from the Claude and Codex transcripts on each executor, with cache hit rates and cost by token type.
• Work from any screen. Use the responsive workspace on desktop or phone and choose Classic, Phosphor, or colorblind-aware themes in light or dark mode.

See It In Action

Shape parallel work on a canvas. Group live chats into named boxes, connect related work, save multiple canvases, and switch to a structured list when that view fits better.

Turn live metadata into a delivery board. Define columns from chat filters and move work by applying the configured tag transitions.

Keep the development loop together. Follow the agent, run focused checks, inspect changed files, stage precisely, and commit from the same workspace.

Steer and unblock from anywhere.	Carry the same visual plan to mobile.

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, permission, provider, endpoint, and preamble settings where supported.

Claude Code requires version 2.1.238 or newer. A model ending in [Nk] sets a per-chat auto-compaction window without a per-model configuration table. For example, gpt-6-astra[922k] launches Claude with --model gpt-6-astra[1m] --autocompact 922k; Claude strips [1m] before calling the provider. N must be an integer from 100 through 1000 (thousands of tokens). The suffix should reflect the model’s supported input limit, not input plus output; Claude reserves additional compaction headroom below it. Garcon retains the annotated model in the chat configuration. Custom endpoints must include that exact annotated ID in their model catalog.

Existing [1m] names keep Claude’s native compaction policy. An explicit [Nk] annotation overrides CLAUDE_CODE_AUTO_COMPACT_WINDOW for that child process only; other environment and Claude settings remain in effect. Changes between numeric caps use a verified runtime control between turns without restarting. The control updates the child process’s environment, which may also be inherited by its tools. Adding or removing a numeric cap, changing other startup-only options, or failing runtime verification resumes the same native session in a new process. Initial launches and one-shot queries retain --autocompact. See Claude’s context-window documentation.

Automate And Delegate

The CLI drives ordinary visible Garcon chats through an already-running server. It covers live catalog discovery, synchronous or detached starts and resumes, steering, exact-turn waiting, status and fenced permission decisions, chat metadata, transcript search and bounded reads, export, handoff, and stop controls.

# Start detached work with explicit lineage.
bun cli/main.ts --runtime controller start-async --cwd /path/to/project \
  --parent 1785337200123456 --agent codex --model gpt-5.4 \
  --permissions acceptEdits "Implement the validation and run focused tests."

# Find prior work, then read exact context around a durable transcript row.
bun cli/main.ts --runtime controller search '"version bump"' --json
bun cli/main.ts --runtime controller read 1785337200123456 84 -B 5 -A 5

# Inspect or steer work without creating a hidden session.
bun cli/main.ts --runtime controller status 1785337200123456 --messages 20
bun cli/main.ts --runtime controller resume-async 1785337200123456 \
  --allow-steer "Address the review finding and rerun the tests."

See the CLI and server guide for the full command and connection reference. bun run build-exe produces standalone Linux x64 and macOS arm64 executables.

The companion cfal/garcon-skills package exposes the same control plane to Claude, Codex, Pi, and other skill-aware agents:

• garcon-captain searches, reads, organizes, monitors, and coordinates chats; garcon-agent starts or resumes a selected agent through the CLI.
• garcon-task starts, resumes, stops, or removes delegated child chats and returns their final output; garcon-message exchanges in-band messages with up to 16 existing chats.
• garcon-schedule creates future or recurring prompts for the current chat; garcon-amp equips a parent with fresh Oracle, Finder, Librarian, and Reporter specialists.
• garcon-ticket manages durable workspace tickets from a chat.

Garcon also installs six editable preambles: a Captain control room for CLI-based chat discovery and coordination, plus the in-chat protocols for chat identity, inter-chat messages, delegated agents, scheduled prompts, and tickets. They are excluded from automatic defaults but can be selected per chat. Fresh workspaces receive all six; existing workspaces receive only missing entries on startup, without overwriting edits or restoring deleted entries. The companion skills provide deeper workflows and Garcon-Amp orchestration.

git clone https://github.com/cfal/garcon-skills.git
cd garcon-skills
./link.sh

The installer links the skills for Claude, Codex, Pi, and other compatible agents. Messages, delegated work, results, and lineage remain visible in Garcon.

Tickets

Open Tickets from a workspace window’s add menu. Create work without starting a chat, switch between list and board, and filter by project, status, priority, label, assignee, or readiness. The detail pane shares properties, comments, relationships, and activity across both layouts. On narrow screens, Back returns to the collection. Status menus provide a keyboard equivalent to board dragging; closing asks for Done or Canceled. Moving a card changes only its status, not its assignee.

New chat from ticket opens the normal New Chat dialog with an editable ticket prompt. Create & open chat first saves a new ticket, then opens that dialog. Choose the executor, directory or worktree, model, permissions, and preambles before starting. Opening or starting the chat does not assign the ticket or change its status; the agent can use ticket tools to claim and update it. Cancelling New Chat leaves the ticket unchanged.

Settings > Automation > Ticket chat prompt configures the template with {{ticket_id}}, {{ticket_title}}, {{ticket_project}}, and {{ticket_description}}. Only {{ticket_id}} is required; the other fields can be omitted, reordered, or repeated. Project is a label, not the chat’s execution directory. Empty templates restore the default. Templates are limited to 32,000 characters and expanded prompts to 256,000 characters; variables inside ticket content are not expanded again. Settings use ui.ticketChat.customPrompt, with no separate model or executor preference.

Project is an editable grouping string, not a directory permission. Enter any name, use an exact project filter, or accept the default from the selected chat’s repository/folder. If Git fails or cannot identify the primary checkout, the default is the chat’s project path. Tickets are also available through the CLI and the garcon-ticket-* agent commands. Agent command settings do not disable human ticket management.

Drafts stay in the current browser tab’s recovery storage when available. Save and comment shortcuts use Cmd/Ctrl+Enter; Enter in a multiline field inserts a newline. After an uncertain save, Retry same request confirms the original operation and refreshes current server values. Conflicts preserve local text for review. Recovery is not a backup: copy text before closing if storage reports a warning. Different accounts and replacement ticket databases never inherit a draft’s write authority.

Comment removal retains previous text in activity history; it is not redaction. Tickets live in the workspace’s tickets.sqlite, independently of chats and transcripts. Back up a live store through SQLite’s backup API or VACUUM INTO, not by copying only the main file while WAL writes are active. A damaged or unknown-schema store is left unavailable for explicit recovery, never rebuilt from transcripts.

Activity’s Open source opens the originating chat at the visible ticket-command result, including older rows outside the loaded transcript. If the transcript was reloaded or the exact result is missing, it opens the chat with a notification instead. Deleted chats cannot be opened. Source addresses remain immutable; navigation never substitutes a row from a replacement transcript.

Path-Prefix Deployments

The webapp, API, and WebSockets can share a runtime URL prefix without rebuilding the frontend: set --base-path /garcon or GARCON_BASE_PATH=/garcon. Reverse proxies must preserve that prefix. See path-prefix deployments.

Remote Executors

Garcon can run agents, files, Git, and terminals on Local and on trusted remote workers. Either side may initiate the connection; both directions use an authenticated Noise-encrypted WebSocket. Worker listeners support native TLS or explicit --no-tls behind a protected TLS proxy.

Add a target in the Executors dialog. Dialing workers receive their full connection credential through GARCON_CONTROLLER_URL, never --connect. Configure the controller’s external address with --public-url or GARCON_PUBLIC_URL; its path must match --base-path. Proxy deployments should not rely on Host fallback. Workspace-wide CLI access is a separate default-off grant.

See executor deployment and onboarding and executor trust, credentials, and revocation before enabling remote access.

Trusted Local Use

To disable authentication for a trusted single-user environment:

bun run start --disable-auth
# or
GARCON_DISABLE_AUTH=true bun run start

Do not expose an unauthenticated instance to an untrusted network. Garcon does not sandbox agents or their commands. Review the security notes before exposing it 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, CLI, and web tests

• web/: SvelteKit and Svelte 5 frontend.
• server/: Bun server, chat lifecycle, providers, Git, auth, and notifications.
• server-agents/: agent-specific runtimes and translation behind the integration boundary.
• common/: shared chat, transport, agent, provider, and API contracts.
• integration-tests/: black-box server, provider, and browser workflows.

Contributions are welcome. See CONTRIBUTING.md for the development workflow. Garcon is licensed under GPL-3.0.