Documentation

Everything you need to install chimaera, run it locally or on a remote host, and drive your agents from one window.

What it is

chimaera is an agent workbench. One static Rust binary (chimaera) is the whole server: it owns your coding-agent sessions as persistent, daemon-owned PTY processes on whatever host owns the work, whether that is your laptop, a dev server, or an HPC login node, and serves a workspace-first web UI around them (file previews, terminals, git state).

Each agent runs one of two ways on the same session, a toggle apart: a rich chat UI (the default), or its real interactive TUI in a daemon-owned PTY (see Chat mode & the TUI). The daemon owns the sessions and windows are just views, so a closed window or a dropped SSH connection never ends a run. A native Tauri app wraps the same UI in real windows.

Install

Native app (recommended)

Grab the macOS app from the download section or the latest release. It bundles the daemon, gives you a home screen of workspaces and remote hosts, and auto-updates itself (signature-verified) on launch.

Build from source

You need stable Rust and Node (see .nvmrc / rust-toolchain.toml for exact versions).

$ git clone https://github.com/martinappberg/chimaera
$ cd chimaera
$ npm --prefix web-ui install
$ npm --prefix web-ui run build      # the daemon embeds web-ui/dist
$ cargo build --release -p chimaera

If you use just, just serve does the UI build + daemon run in one step, and just app-build bundles the native app.

Run locally

Start the daemon; it prints the URL to open.

$ chimaera serve
  → workbench on http://127.0.0.1:9700/#token=…

$ chimaera serve --port 9700   # pick the port
$ chimaera status               # what's running
$ chimaera doctor               # environment sanity check

The URL carries a bearer token in the fragment, so anyone with the link on the machine can attach. Open it in a browser, or just use the native app, which manages the local daemon for you.

Connect to a remote host

chimaera connect <host> shells out to your system ssh, so ProxyJump, ControlMaster, and 2FA from your ~/.ssh/config all just work. It installs the daemon into ~/.chimaera on the host if it's missing, starts or attaches to it, tunnels the port, and opens the UI.

$ chimaera connect gpu-node
  → detecting target (uname -sm) … linux/x86_64
  → installing daemon in ~/.chimaera … ok
  → starting daemon … listening on :9700
  → tunnelling 127.0.0.1:9700 → gpu-node:9700 … ok
  → opening workbench ✓

No root and no containers are needed on the remote. The daemon is a single static binary that installs under your home directory. From the native app, add the host once on the home screen and connect with a click (probe → auto-install → start → tunnel, shown as progress states).

Workspaces & windows

A window is a workspace: a folder, local or remote. Opening it gives you the file tree, previews, and git state for that folder, plus as many agent and terminal sessions as you want living inside it. Sessions belong to the workspace and the host-side daemon, not to the window, so windows are detachable views you can close and reopen without losing anything.

• Split panes, tabs, and drag-and-drop arrange terminals and previews side by side.
• Focus mode collapses the chrome down to the work; a session strip keeps you oriented.
• Layout is per-window view state, owned by the daemon and restored when you return.

Agents

The launcher detects the agent CLIs you have installed and can install or update them from official sources (curated scripts, checksum-verified, never sudo). Binaries live under ~/.chimaera, and your credentials stay entirely yours (in HOME and your login-shell environment).

• Claude Code (claude) and Codex: first-class, and run in chat mode or as the real TUI.
• Gemini CLI and Antigravity (agy): detected and launchable as TUIs, but not yet first-class (no managed install or attention state).
• Plain shells: first-class workspace sessions too.

Run as many as you want side by side. Each agent's state becomes an attention signal so a rail badge and the session strip tell you which one is waiting on you, and approval always happens in context, never out of band. Sessions auto-name after what they're actually doing, and ended conversations drop into a per-workspace Recents list you can resume from.

Chat mode & the TUI

Every agent runs one of two ways on the same session, a toggle apart. New sessions open in chat mode by default; the setting agents.defaultView changes that, and any session flips between the two live.

• Chat mode drives the CLI over its structured JSON protocol (Claude Code over stream-json, Codex over codex app-server) and renders a first-class chat UI: streamed thinking, tool cards, permission and question prompts, model/effort pickers, rewind, and inline previews of the files each turn produced. It reconnects losslessly, so a dropped socket never loses the transcript.
• The real TUI runs the actual claude / codex terminal in a daemon-owned PTY: full CLI fidelity, and it bills exactly like the interactive terminal.

Rewind (Claude): hover a past message to revert the files that turn changed, or fork the conversation from that point. Chat sessions survive a disconnect; they do not yet survive a daemon restart, so a restart retires them to Recents for manual resume.

File previews

The previews are the reason you can retire code-server. The server extracts and the client renders, so whole files are never loaded into the browser.

• Images: with zoom, pan, and fit.
• Markdown: rendered, with an edit/preview toggle.
• CSV / TSV: paged tables, gzip and BGZF included.
• PDF: bundled viewer, no CDN (air-gapped safe).
• Notebooks: .ipynb with outputs.
• HTML reports: self-contained and sandboxed, the MultiQC / FastQC class of scientific output.

Lightweight editing is built in (CodeMirror, ⌘S to save, a dirty indicator), enough to fix a script, not a full IDE.

Git & worktrees

A source-control panel for the workspace's repo: a branch header with ahead/behind counts, and every changed path grouped into conflicts, staged, changes, and untracked. Click any row to open a side-by-side diff in an adjacent pane. It is review-first — status and diff, not stage / commit / push; those stay in a terminal for now.

• Worktrees. Spin a branch into its own openable window: create a worktree under a managed root and spawn an agent or terminal into it. Removal is fenced (managed root only, no live session, clean tree), and the branch itself survives.
• A branch per agent. The Branches view maps which session runs in which worktree, derived from each session's working directory, so you can jump straight to the agent on another branch.
• Session-scoped changes. Review exactly what one agent touched, cross-referenced with live git status.

Refresh is event-driven (a file save, an agent write, a terminal command finishing), never a status poll. Git is resolved through your login shell and needs version 2.15+; on old-git or shared-storage clusters the panel turns the two common dead-ends (git too old, "dubious ownership") into one-step fixes.

Linked terminals

Hand an agent a leash to a live shell, the one that already has your modules loaded and your conda environment active, instead of paying setup cost on every command. Links are user-granted, scoped to a specific terminal, and every command the agent runs through the link is audited in that terminal's own scrollback so you can see exactly what happened.

Staying current

Two things keep themselves current so a running setup keeps pace with releases:

• The daemon is replaced on connect when it is older than the client, silently if it has no live sessions, otherwise behind an explicit "update" action that spells out what it ends. An idle shell holding a module load or conda environment is never killed without asking. This works the same for local and remote daemons.
• The native app checks GitHub releases on launch and offers a one-click "update & restart"; the download is signature-verified (minisign) before it installs.

Platforms

macOS and Linux.

• Daemon: fully static musl binaries for x86_64 and aarch64 Linux that run on old-glibc HPC systems (verified on glibc 2.17, no root), plus an aarch64 macOS build.
• Native app: macOS on Apple Silicon.
• Windows: untested.

The daemon is built to live on shared login nodes: bounded allocations, hard ceilings on preview extraction, and about 150 MB RSS under a core at steady state. Durable state is append-only, size-capped JSONL under ~/.chimaera, with no SQLite anywhere near NFS/Lustre.

Troubleshooting

The remote daemon is a stale version

Reconnect: chimaera connect <host> replaces an outdated daemon (asking first if it has live sessions). Or force it from the CLI with chimaera connect <host> --update-daemon.

claude isn't found on the remote

Non-interactive SSH often has a slimmer PATH. chimaera spawns agents through your login shell so they get the same environment as an interactive session, but the agent still has to be installed and on that login shell's PATH. Install or update it from the launcher, or check chimaera doctor.

2FA / no public keys on the cluster

If your cluster requires interactive 2FA (e.g. Duo) and forbids pubkeys, keep a live ControlMaster connection open (the way you normally SSH in); chimaera reuses it for non-interactive commands.

License

chimaera is licensed under the GNU AGPL-3.0, free for everyone to use, self-host, and modify. If you want to build a closed-source product or service on chimaera, a commercial license is available: contact the author. Contributions require a CLA (see CONTRIBUTING.md).