Documentation

A workspace for everything you do with agents. Open a project, start an agent, explore its outputs, and bring your tools and context together.

What it is

Chimaera is an agent workbench: your agents, the files they work on, and the context of your project in one workspace. Use it to build software, prepare documents, work with data, and carry a project across those activities.

A workspace starts with a folder. Open conversations, file previews, terminals, Git views, and web apps beside one another. The dashboard helps you direct several agents; Timeline and Knowledge help you return to the work. Extensions add tools and workflows to the same environment.

The native app and browser share the same UI. A server on the workspace’s host owns the sessions and files. It can run on your machine, on a remote server over SSH, or inside a Slurm compute job.

Install

Native app (recommended)

Grab the macOS, Linux, or Windows app from the download section or the latest release (macOS .dmg; Linux AppImage / .deb / .rpm; Windows .exe installer, beta). It bundles the daemon, gives you a home screen of workspaces and remote hosts, and offers signature-verified updates.

Build from source

Use Node 26 and the Rust toolchain pinned in rust-toolchain.toml.

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

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

Your first workspace

1. Open a folder from the app’s home screen. Choose a project you want to work on.
2. Start an agent. Choose a provider in the launcher. Install its CLI if needed, then choose Sign in to follow the provider’s login flow from the app. The login belongs to the host where the workspace runs.
3. Give it a concrete task. For example, summarize the files in this folder, improve a document, or make a change to an app.
4. Open the result beside the conversation. Click a file in the tree or an output in the chat. Select the part you want changed and refer to it in a follow-up.
5. Shape the workspace. Split a pane, add a terminal, start another agent, or open the dashboard to see where things stand.

Add Knowledge and document tools from Extensions as you need them. The feature catalog gives the detailed behavior of each surface.

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).

When the host is a cluster, Chimaera opens its cluster workflow so you can start a compute job and open workspaces inside it.

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.

Dashboard & coordination

Open Dashboard in the rail (or press ⌘/Ctrl 0) to see Needs you, Since you left, and the running agents. Answer supported chat permissions inline, or jump into a conversation for a question or review.

Agents in the same workspace can see each other’s recent work and exchange messages. Settings → Agents controls communication and whether a message may wake an idle agent. A wake starts a provider turn.

Add a Mastermind when you want a coordinator. Ask it to brief you, read the workspace’s activity, or help direct work across agents. You choose its authority; the workspace’s attention controls keep decisions visible.

Agents

Chimaera launches the agent’s own runtime in your workspace, using that host’s account, environment, project instructions, skills, and configured connections. A local workspace uses your local setup; an SSH workspace uses your setup on the remote host. The launcher detects installed agent CLIs and offers managed install and update flows from their official sources. Choose Sign in in the launcher or Settings → Agents, or type /login in chat to open the provider’s sign-in card.

• Claude Code and Codex: structured chat and real terminal sessions, with conversation switching between those views.
• Antigravity, Grok Build, and Cursor CLI: structured chat through ACP, plus their CLI launch paths. Use chat for Chimaera’s workspace messaging integration.
• Plain shells: workspace terminals for running commands directly or linking to an agent.

Chimaera adds workspace tools for agent communication, linked terminals, and extensions. Models, reasoning controls, permissions, and resume behavior follow each provider’s integration. The launcher and chat show the controls available for that agent. Sign-in, usage limits, and billing are governed by the provider; Chimaera does not include model usage.

Chat mode & the TUI

New supported agent sessions open in chat mode by default. It renders streamed responses, tool calls, permission prompts, questions, and file outputs around a composer. Provider-specific controls appear where supported.

Claude Code and Codex can switch a conversation between chat and their real terminal UI. The switch resumes the conversation in the chosen surface; it is not a simultaneous view of one running process. Antigravity, Grok Build, and Cursor CLI do not offer that same-session switch.

Use agents.defaultView to choose the starting view for new sessions. Saved conversations reopen in their saved view. Failed chats that already contain a prompt or saved conversation retain their error and recovery actions.

Rewind and conversation branching are available for supported Claude/Codex operations. See the chat guide for provider-specific behavior.

Follow the work

When an agent shares a plan, a card above the composer shows its steps and progress. Open a supported subagent’s conversation from its activity row to inspect the work in a separate, read-only chat.

Claude Code’s /loop and /goal, and Codex’s /goal, show up in an Ahead card. See what will resume the agent, when, and why. Open a row for details and the controls available for that provider. A conversation with pending work stays unfinished in the rail and dashboard, and its done notification waits until that work ends. See loops and goals.

The chat header’s usage meter shows context and plan limits where the agent reports them, drawing attention as a limit approaches. Click it for details, or open Settings → Agents → Plan usage for account limits and reset times. Cursor CLI does not currently expose usage to Chimaera.

File previews & precise feedback

Open a file from the tree or chat to view it beside the agent. Split panes and tabs let you compare outputs and keep source material close.

• Text and Markdown: source, reading, and live editing views; math, callouts, linked notes, embeds, and Mermaid diagrams.
• Tables: CSV/TSV, compressed text tables, Excel and OpenDocument spreadsheets, and Parquet.
• Documents: PDFs, Word documents, PowerPoint decks, and Markdown slide decks.
• Visuals and media: images, video, audio, Canvas, Excalidraw, and draw.io documents.
• Interactive work: notebooks with outputs, sandboxed HTML reports, and live web apps in browser panes.

Point to the part that matters. Reference a passage, PDF area, image region, table selection, notebook cell, slide, or media moment in a chat. Chimaera carries the file and location into your feedback.

Text and Markdown support lightweight editing with save conflict handling and draft recovery. Other formats use dedicated viewers. Size limits, paging, and bounded reads depend on the format; see files and previews.

Live apps: ask an agent to open its web app, open a detected localhost URL from a terminal, or add a browser pane, to use a web app beside your agent. Chimaera’s proxy also reaches apps on the remote workspace’s host.

Files & uploads

The file tree and a Finder-style column browser are full file managers, not just a read-only tree.

• Preview as you browse. Select a file in the Finder-style browser to see a preview beside the folder columns. Double-click, press Enter, or choose Open to give it a full file tab.
• Manage files. Create, rename, delete, and copy / cut / paste files and folders from a right-click menu or the keyboard. Copies and moves run server-side, so bytes never round-trip the browser. Symlinks are marked (broken ones too).
• Reference by drag. Drag a file or folder from the tree onto a session to type its path: an @mention for an agent, a shell-quoted path for a terminal. Nothing is copied; the file is already on the host.
• Bring files in. Drop a file from your desktop onto a session or a folder, or paste a screenshot. The bytes stream to the daemon that owns the session, so a file you drag from your laptop lands on the remote host the agent can read. Uploads are capped and streamed, never buffered in RAM.
• Take outputs out. On a remote workspace, download any file back to your local machine from its row menu: the outputs an agent produced on the cluster, brought home.

Git & worktrees

A source-control panel for repositories in the workspace: 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.

• History. Browse repository commits, file history, and branch changes. Session records connect an agent’s work to its changed files and available Git history.
• 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.
• Start a chat in isolation. Turn on In a new worktree in the agent launcher to give a new chat a fresh branch and checkout. The chat opens immediately while Chimaera prepares the worktree.
• 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 follows file saves, agent writes, and completed terminal commands, with a periodic backstop for changes made outside the app. 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.

History & Knowledge

All sessions brings together past agent work, its transcript, timing, and recorded file changes. A project can have session history with or without Git. Timeline records agent activity, notable commands, messages, and other workspace events; the dashboard uses it for Since you left.

Knowledge appears when an enabled extension provides it, such as Mycelium. It lets you search and browse recorded findings, decisions, conventions, to-dos, and handoffs, follow their source references, and open the underlying files. The provider reads project records; agents create and maintain those records through their own workflows.

Open Extensions, install and enable a knowledge provider for the workspace, and follow its setup instructions. See Timeline and Knowledge for the sources and views.

Extensions, skills & connections

The Extensions view brings together workbench plugins, agent plugins, skills, and connections. Each extends a different part of your environment.

• Workbench plugins run as WebAssembly components in Chimaera. Install them from the first-party catalog, a repository release, or a local build, then enable them per workspace. Review requested capabilities and trust before granting access.
• Mycelium, LaTeX, and Typst are first-party extensions: project Knowledge, and LaTeX/Typst compilation to PDF beside the source with diagnostics and agent tools. Follow the extension’s setup instructions to install its compiler.
• Agent plugins and skills are reported by the agents and installed through their native managers. Chimaera makes them visible in the workspace.
• Connections shows your agents’ configured MCP services and hosted connectors, with status and provider sign-in flows where available.

Plugin details expose capabilities, activity, updates, and rollback. Developers can add tools, provider data, and plugin UI using the extension authoring guide.

Clusters

Connect a Slurm cluster from the home screen to open its cluster page. Start a job with the resources and time you need, then open one or more workspaces inside it. Agents and the workspace server run on the compute node; the login node handles short connection and scheduler commands.

The cluster page shows jobs, their resources and remaining time, and the workspaces inside them. When a job ends, continue a saved workspace in a new job. Configure startup commands for modules and environments on the host or workspace.

Job management uses Slurm. See the cluster guide for setup, reconnection, and site-specific behavior.

Persistence & recovery

Closing a workspace window or losing the client connection leaves the server’s agent and terminal processes running. The host doing the work must remain awake and available. Reconnecting restores the view.

A daemon restart ends those processes. With daemon.restoreSessions enabled, the ledger restores supported saved conversations and starts fresh shells at their saved locations. Native conversation handles and provider transcripts determine whether a conversation can resume.

Pick Up Interrupted Work After a Restart (chat.resumeAfterRestart) can send a resumed chat a message to continue interrupted work. This starts a turn on your provider account. Shell environments and arbitrary running processes are not checkpointed. See the recovery guide.

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.

Settings

Everything is meant to be customizable. Settings live in a single settings.json the daemon owns; the in-app Settings panel and hand-editing the file (over SSH with vim, say) are both first-class against it, and a change shows up live. Curated light and dark themes are injected into the agents' own TUIs too, so the terminals match the workbench.

Platforms

macOS and Linux, with Windows in beta.

• Daemon: fully static musl binaries for x86_64 and aarch64 Linux that run on old-glibc systems (verified on glibc 2.17, no root), plus an aarch64 macOS build.
• Native app: macOS on Apple Silicon, and Linux as an AppImage / .deb / .rpm.
• Windows (beta): a native app whose daemon runs the Linux musl binary inside WSL2, reached over localhost. The engine and the SSH-connect path are CI-tested; the first-run wizard and the interop askpass chain haven't had a hands-on pass on retail hardware yet, so it ships as a clearly-labeled beta download. Expect to walk through a couple of setup steps on first launch.

The daemon uses bounded preview extraction and capped state. Durable history uses JSONL and small atomic JSON files under ~/.chimaera, suitable for shared filesystems. Cluster workspaces normally run inside compute jobs.

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.

Develop & extend

For changes to Chimaera itself, start with AGENTS.md and .github/CONTRIBUTING.md. The repository has area maps and matching Claude/Codex workflows for development and live verification.

For an extension, use the plugin guide for people and agents: choose the extension point, build a component, declare capabilities, install it locally, and verify it in an isolated workspace. The documentation index separates current behavior from historical design plans.

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 .github/CONTRIBUTING.md).