Chan is a supercharged terminal emulator, free and open source under the Apache 2.0 license.
It builds up in layers, and one binary carries all of them:
- A terminal emulator. Terminals open in tabs and split panes. The session behind a terminal lives in a server process, not in the window, so a window can reload, close or attach from another machine while the shell keeps running.
- Scriptable from the shell, the keyboard and the mouse. Every chan terminal has the
cscommand, which drives the window it runs in: open a file, split a pane, start a named terminal, type into another tab and read its scrollback. The same actions sit behind the command launcher and shortcuts, and behind menus and drag and drop. - A multiplexer of its own, and tmux. Windows, panes, tabs and named sessions that outlive their views. A
tmux -CCrun in a chan terminal turns that tmux server's windows and panes into chan's. - Local and remote, the same. The process that owns the terminals is a server with an HTTP and WebSocket API. The desktop app embeds it for local work;
chan devserverruns it headless on another machine. - A devserver over a TCP tunnel. A remote devserver is reached over whatever TCP path already exists: an ssh port forward, a VM, a container.
- A devserver through a gateway. For an always-on setup shared with other people, a devserver dials out to a chan gateway, a set of services you host yourself, which publishes it behind sign-in.
Around the terminal, chan turns any directory into a workspace: search, a Markdown editor with diagrams and slide decks, a file browser, a graph of the project, a dashboard, and teams of coding agents in named tabs.
Nothing is an online service: the desktop app, the headless devserver and the gateway all build from this repository. design.md states each layer in full.
Download Chan Desktop for macOS, Windows or Linux, or the chan command for servers, from chan.app. The user manual is at chan.app/manual.
Building from source needs Rust through rustup and Node.js with npm. The Rust toolchain is pinned in rust-toolchain.toml and installs itself on first use.
make chan # the release CLI with both web apps embedded
make chan-desktop # the desktop app for the host platform
make help # every build, package and check targetOne repository builds everything.
- Rust. The root Cargo workspace holds the
chanbinary and the libraries under it, layered in one direction.chan-workspaceis the core: a sandboxed filesystem over a directory, the workspace registry, search and the graph, with no knowledge of HTTP.chan-libraryhosts workspaces and terminal sessions.chan-serverwraps them in HTTP and WebSocket routes.chanand the desktop drive the stack. - Web. An npm workspace holds the Svelte apps: the workspace app (terminal, editor, file browser, graph, dashboard) and the launcher. Both are embedded into the binary at build time, so nothing but the binary is needed at runtime: no Node.js, no Python, no daemons. The terminal core is Ghostty's libghostty-vt compiled to WebAssembly.
- Desktop. chan-desktop is a Tauri shell that embeds the same server and opens its windows as native webviews. The desktop binary is also the CLI when invoked as
chanorcs. - Gateway. The gateway is a Cargo workspace of its own, backed by Postgres. It is not a member of the root workspace, so the single binary never links Postgres or OAuth.
Chan is developed by small teams of AI coding assistants coordinated by the project owner, using chan's own Team Work tooling. team/README.md describes the process.
- crates/ - the Rust crates of the root Cargo workspace: the
chanbinary and its libraries. - desktop/ - chan-desktop, the Tauri shell, also a member of the root workspace.
- web/ - the npm workspace: the workspace app, the launcher, the terminal widget (
ghostty-web-ng), the gateway's account app (profile), shared code (web-shared), and the chan.app site with the user manual (marketing). - gateway/ - the gateway's Cargo workspace: its services, the operator CLI, the database migrations and the decision records.
- packaging/ - what the Makefile's package targets drive: distro packages, container images, Kubernetes manifests, Nix and FreeBSD builds.
- scripts/ - the pre-push gate and the checks it runs, and the end-to-end suites under
scripts/e2e/. - fixtures/ - recorded inputs the tests read: tmux control-mode captures, a sample workspace for search.
- docs/ - the guides listed at the end of this file.
- team/ - the development process: accepted scope in
team/roadmap/, release records inteam/release/. - .agents/ - the standards contributors and coding agents work to.
At the root, design.md is the whole-system design, CONTEXT.md the product vocabulary, CHANGELOG.md the history, and the Makefile the public command surface for builds, packages and checks.
Contributors and agents start at .agents/README.md, which holds the project's standards and the order to read them in. CONTRIBUTING.md is the practical guide: setup, build and test, the pre-push gate and the pull-request workflow. Security reports go through SECURITY.md.
The architecture is documented next to the code it describes. A design.md is the design of record for the directory it sits in: what the component owns, its boundaries and contracts, the invariants it holds, and the reasons behind them. These documents describe the system as it is; how it got there is in CHANGELOG.md. Where a README.md sits beside one, the README is the practical side: what the component is for and how to run or use it.
Start with design.md, the whole-system reference: the layers of the product, the components, the runtime shapes (local, a devserver over a tunnel, a devserver through a gateway) and the invariants. It stays above the level of routes, flags and timeouts. From there, read up the stack every window sits on (chan-workspace, chan-library, chan-server) and then the document for the part you are changing.
Core, the root Cargo workspace from the bottom up:
- crates/chan-workspace - the core: filesystem gates, workspace registry, search, graph, state placement, locking.
- crates/chan-library - the host: workspace and terminal tenants under one server, the window registry, terminal sessions, tmux connections.
- crates/chan-server - the serving layer: per-tenant HTTP/WS, SPA embed, MCP host, devserver builder.
- crates/chan - the CLI binary: dispatch, process lifecycle, service supervision, self-upgrade.
- crates/chan-shell -
cs: the control-socket wire contract and the client that speaks it. - crates/chan-llm - the MCP tool sandbox exposed to external agent CLIs.
- crates/chan-tmux - the tmux control-mode protocol: stream framing, notifications, commands, layouts.
- crates/chan-report - repository reports: the walker, the JSONL schema, the COCOMO model.
- crates/chan-metrics - the process-wide counters and the metered I/O wrapper the serving and transport code feed.
- crates/chan-systemd - the systemd boundary: notify, watchdog, fdstore, unit render and classification.
- crates/chan-winpipe - the Win32 boundary of chan's named pipes: the account SID, owner-only pipes, the account serving a pipe.
- crates/fetch-models - build-only helper that produces the embedded-model tarball.
Desktop and web, the surfaces a user sees:
- desktop - the Tauri shell: windows, exact-origin trust, native IPC.
- web/packages/workspace-app/src - the web frontend: the SPAs and how each is served, the color system.
- web/packages/workspace-app/src/editor - the CM6 editor surface.
- web/packages/launcher - the launcher SPA and its three-surface serving.
Tunnel, the transports between a desktop, a devserver and a gateway:
- crates/chan-tunnel-proto - the shared wire contracts.
- crates/chan-tunnel-client - the dial-side client embedded by
chan devserver. - crates/chan-wireguard - the in-process WireGuard peer and TCP stack the devserver's dial can run through.
- crates/chan-tunnel-server - the terminator embedded by the gateway.
- crates/chan-revtunnel - reverse port forwarding from a devserver to the connected desktop (
cs tunnel); distinct from the gateway tunnel. - crates/chan-tls - the TLS trust decision the desktop's clients and updater, the devserver's tunnel dial, the CLI's self-update and
chan metrics --url, and the gateway's WireGuard agent share.
Gateway, a separate Cargo workspace (the self-hosted account, sign-in, and proxy surface):
- gateway - the whole-gateway reference: publication, account and desktop lifecycles, control and data planes, entry, and isolation.
- gateway/crates/identity - sign-in, PATs, discovery, desktop entry: the public account surface (gw.{domain}).
- gateway/crates/profile - the authoritative user store.
- gateway/crates/devserver-proxy - the public data-plane edge for tunneled devservers ({proxy}.proxy.{domain}).
- gateway/crates/devserver-control - the fleet control plane: proxy directory, admission, kill routing.
- gateway/crates/wireguard-agent - the agent on a proxy node that makes a kernel WireGuard interface's peers follow the gateway's active peers.
- gateway/crates/gateway-common - the contracts the gateway services share.
- gateway/crates/admin - the operator CLI.
Using and extending chan:
- docs/extensions.md - how Chan uses extensions and how to build one.
- docs/config-reference.md - every persisted configuration file and field.
- docs/metrics.md - the process metrics: what the Dashboard's Metrics slide,
chan metricsand/api/metricsreport, and the optional systemd-report source.
Building and testing it:
- docs/contributing/linux-and-macos.md - the gates in a Linux container that mirrors CI, on a Linux host or through a VM on macOS.
- docs/contributing/windows-and-linux.md - building chan-desktop for Windows, and developing chan on a Windows machine.
- gateway/docs/dev-setup.md - a local gateway in the production layout.
- scripts/e2e/README.md - the end-to-end suites and the rules for running them.
- packaging/README.md - how the packages and deployment artifacts are built.