README
¶
crabswarm
Swarm Claude Code using tmux sessions, so you can chat with Claude while lying in bed.
Markdown previewer
crabswarm preview serves a browser-based, GitHub-flavored markdown previewer
with live reload, multi-root support, a file tree, and a toggleable table of
contents.
# Add the current directory (default) as a preview root and print its URL.
crabswarm preview
# Add a specific directory.
crabswarm preview ./docs
# List the roots the running daemon knows about.
crabswarm preview list
# Drop a root by its NAME or ID (see `preview list`).
crabswarm preview remove docs
The first crabswarm preview starts the preview server as a background daemon
under cmdman (expected on PATH);
subsequent invocations just add another root to the running daemon. preview,
preview list, and preview remove all talk to that daemon, so they require
cmdman for the daemonized path.
Stopping is cmdman's job:
cmdman stop crabswarm-preview
If you don't want cmdman, run the server in the foreground yourself — the same process cmdman would daemonize:
crabswarm preview __serve --addr 127.0.0.1:6419
preview __serve needs no cmdman; add roots against it with crabswarm preview list/remove or the ConnectRPC API directly.
Configuration
The preview block of the crabswarm config (defaults < file < env < flags):
| Key | Env | Default | Meaning |
|---|---|---|---|
preview.addr |
CRABSWARM_PREVIEW_ADDR |
0.0.0.0:6419 |
TCP listen address of the preview HTTP server. |
preview.daemon_name |
CRABSWARM_PREVIEW_DAEMON_NAME |
crabswarm-preview |
cmdman command name the previewer runs under. |
preview.addr can also be overridden per-invocation with --addr.
Security warning
The default preview.addr is 0.0.0.0:6419 so phones and tablets on the
tailnet (Tailscale MagicDNS) can reach it. There is no authentication: the
server exposes registered roots' file contents to anyone who can reach the
port. On untrusted networks, set preview.addr to 127.0.0.1:6419 or firewall
the port accordingly.
License
Unlicense - Public Domain
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api anchors code generation for the crabswarm proto schema; it holds no Go source of its own.
|
Package api anchors code generation for the crabswarm proto schema; it holds no Go source of its own. |
|
cmd
|
|
|
crabswarm
command
Package main is the entry point for the crabswarm CLI.
|
Package main is the entry point for the crabswarm CLI. |
|
crabswarm/commands
Package commands contains the cobra commands for crabswarm.
|
Package commands contains the cobra commands for crabswarm. |
|
Package crabswarm implements the crabswarm service backing the binary of the same name: the server, the Claude Code hook handlers, and the git helpers.
|
Package crabswarm implements the crabswarm service backing the binary of the same name: the server, the Claude Code hook handlers, and the git helpers. |
|
chat
Package chat brokers the rooms crabswarm participants — agents running in cmdman-managed containers and humans on the host — attend to talk to each other.
|
Package chat brokers the rooms crabswarm participants — agents running in cmdman-managed containers and humans on the host — attend to talk to each other. |
|
chat/auth
Package auth proves that a caller may perform the host-side chat operations.
|
Package auth proves that a caller may perform the host-side chat operations. |
|
chat/cli
Package cli is the caller's half of the chat broker: it dials the daemon socket, carries the caller's credential on every RPC, and renders what comes back as plain text that an agent can parse as easily as a human can read it.
|
Package cli is the caller's half of the chat broker: it dials the daemon socket, carries the caller's credential on every RPC, and renders what comes back as plain text that an agent can parse as easily as a human can read it. |
|
chat/cli/tui
Package tui draws the admin's watch screen: one room's conversation as it happens, who is attending it and in what state, and the message to send into it — addressed with an `@` the room reads as a mention.
|
Package tui draws the admin's watch screen: one room's conversation as it happens, who is attending it and in what state, and the message to send into it — addressed with an `@` the room reads as a mention. |
|
chat/internal/cmdman
Package cmdman types lines into a member's terminal through the cmdman CLI.
|
Package cmdman types lines into a member's terminal through the cmdman CLI. |
|
chat/internal/schema
Package schema holds the chat store's SQL and turns it into the two things that must never disagree: the DDL the store creates its tables from, and the input sqlc compiles the queries in ../db against.
|
Package schema holds the chat store's SQL and turns it into the two things that must never disagree: the DDL the store creates its tables from, and the input sqlc compiles the queries in ../db against. |
|
chat/notify
Package notify wakes a member whose harness has finished its turn, so a message that just mentioned them is read now rather than whenever they next happen to look.
|
Package notify wakes a member whose harness has finished its turn, so a message that just mentioned them is read now rather than whenever they next happen to look. |
|
chat/nudge
Package nudge holds the words a member is woken with and the address those words name the sender by.
|
Package nudge holds the words a member is woken with and the address those words name the sender by. |
|
chat/resolver
Package resolver places the holder of an identity token in the chat topology: which room they talk in and which team namespaces their name.
|
Package resolver places the holder of an identity token in the chat topology: which room they talk in and which team namespaces their name. |
|
cli
Package cli holds crabswarm's CLI-presentation code — rendering resolved configuration and other terminal output.
|
Package cli holds crabswarm's CLI-presentation code — rendering resolved configuration and other terminal output. |
|
git
Package git implements crabswarm's git helpers: a ghq-style bare clone that lays out a repository under a base directory and checks out its default branch as a worktree, plus a thin worktree wrapper that resolves the repository from the current directory.
|
Package git implements crabswarm's git helpers: a ghq-style bare clone that lays out a repository under a base directory and checks out its default branch as a worktree, plus a thin worktree wrapper that resolves the repository from the current directory. |
|
hook
Package hook holds crabswarm's Claude Code / Codex hook implementations and the helpers they share.
|
Package hook holds crabswarm's Claude Code / Codex hook implementations and the helpers they share. |
|
hook/exec
Package exec implements `crabswarm hook exec`: a declarative way to wire Claude Code and Codex hooks.
|
Package exec implements `crabswarm hook exec`: a declarative way to wire Claude Code and Codex hooks. |
|
hook/path
Package path implements `crabswarm hook path`: hooks that validate the file path a tool is about to touch and block the tool call when the path breaks a rule.
|
Package path implements `crabswarm hook path`: hooks that validate the file path a tool is about to touch and block the tool call when the path breaks a rule. |
|
issues
Package issues reads a beads issue database through the `bd` command line tool.
|
Package issues reads a beads issue database through the `bd` command line tool. |
|
issues/cli
Package cli renders the output of the issues commands.
|
Package cli renders the output of the issues commands. |
|
issues/mermaidlint
Package mermaidlint validates the mermaid diagrams carried by issue text by running the mermaid-lint command line tool over it.
|
Package mermaidlint validates the mermaid diagrams carried by issue text by running the mermaid-lint command line tool over it. |
|
mcp
Package mcp is the crabswarm MCP server a harness reaches its agent's room through; chat is its first tool family.
|
Package mcp is the crabswarm MCP server a harness reaches its agent's room through; chat is its first tool family. |
|
mcp/chat
Package chat serves a crabswarm chat room's member verbs as the MCP server's first tool family.
|
Package chat serves a crabswarm chat room's member verbs as the MCP server's first tool family. |
|
mcp/codexproxy
Package codexproxy runs a remote Codex TUI through a WebSocket proxy that stamps the TUI's chat identity on every thread it starts.
|
Package codexproxy runs a remote Codex TUI through a WebSocket proxy that stamps the TUI's chat identity on every thread it starts. |
|
preview
Package preview implements `crabswarm preview`: a browser-based GitHub-flavored markdown previewer served over TCP so phones and tablets on the tailnet can reach it.
|
Package preview implements `crabswarm preview`: a browser-based GitHub-flavored markdown previewer served over TCP so phones and tablets on the tailnet can reach it. |
|
preview/httpapi
Package httpapi composes the previewer's HTTP surface: the connect-go PreviewService and IssuesService handlers, a /healthz probe, raw file serving under /raw, the render stylesheets under /assets/css, and the single-page-app static files with an index.html fallback.
|
Package httpapi composes the previewer's HTTP surface: the connect-go PreviewService and IssuesService handlers, a /healthz probe, raw file serving under /raw, the render stylesheets under /assets/css, and the single-page-app static files with an index.html fallback. |
|
preview/render
Package render turns markdown source into GitHub-flavored HTML with a table of contents and a document title.
|
Package render turns markdown source into GitHub-flavored HTML with a table of contents and a document title. |
|
preview/render/alert
Package alert provides a Goldmark extension for GitHub-style alerts.
|
Package alert provides a Goldmark extension for GitHub-style alerts. |
|
preview/render/mathjax
Package mathjax is a goldmark extension that emits MathJax-compatible markup for inline ($...$) and block ($$...$$ or ```math fences) math, to be typeset client-side by MathJax (tex-mml-chtml.js).
|
Package mathjax is a goldmark extension that emits MathJax-compatible markup for inline ($...$) and block ($$...$$ or ```math fences) math, to be typeset client-side by MathJax (tex-mml-chtml.js). |
|
server
Package server hosts the crabswarm daemon: one gRPC server on a Unix socket serving the hook audit service beside both halves of the chat broker, held to a single instance per socket by a lock file next to it.
|
Package server hosts the crabswarm daemon: one gRPC server on a Unix socket serving the hook audit service beside both halves of the chat broker, held to a single instance per socket by a lock file next to it. |
|
statusline
Package statusline implements `crabswarm statusline render`: it reads a Claude Code status line JSON payload from a reader and renders it through a Go text/template supplied by the caller.
|
Package statusline implements `crabswarm statusline render`: it reads a Claude Code status line JSON payload from a reader and renders it through a Go text/template supplied by the caller. |
|
internal
|
|
|
cmdsignals
Package cmdsignals lists the OS signals that should cancel top-level CLI execution.
|
Package cmdsignals lists the OS signals that should cancel top-level CLI execution. |
|
libver
Package libver pins the module-wide, release-controlled version string.
|
Package libver pins the module-wide, release-controlled version string. |
|
loggerfactory
Package loggerfactory builds a slog.Logger configured by two pflag.BoolFunc flags ("--log" and "--log-level") and registers those flags on a Cobra command's persistent flag set.
|
Package loggerfactory builds a slog.Logger configured by two pflag.BoolFunc flags ("--log" and "--log-level") and registers those flags on a Cobra command's persistent flag set. |
|
stdiopipe
Package stdiopipe provides cancellable readers and writers backed by os.Stdin, os.Stdout, and os.Stderr via io.Pipe.
|
Package stdiopipe provides cancellable readers and writers backed by os.Stdin, os.Stdout, and os.Stderr via io.Pipe. |
|
supervisor
Package supervisor starts a command under a process supervisor and, when a readiness target is given, waits until that target answers.
|
Package supervisor starts a command under a process supervisor and, when a readiness target is given, waits until that target answers. |
|
supervisor/cmdman
Package cmdman implements supervisor.Supervisor on top of the cmdman executable.
|
Package cmdman implements supervisor.Supervisor on top of the cmdman executable. |
|
templateutil
Package templateutil centralizes the text/template helpers shared by the crabswarm template-rendering call sites (hook exec command rendering and the status line renderer).
|
Package templateutil centralizes the text/template helpers shared by the crabswarm template-rendering call sites (hook exec command rendering and the status line renderer). |
|
versioninfo
Package versioninfo combines a project-supplied version string with the VCS / build info embedded by `go build` (via runtime/debug.ReadBuildInfo).
|
Package versioninfo combines a project-supplied version string with the VCS / build info embedded by `go build` (via runtime/debug.ReadBuildInfo). |
|
pkg
|
|
|
claudehook/handler
Package handler defines handler for claude hook
|
Package handler defines handler for claude hook |
|
claudehook/types
Package types contains handwritten Claude Agent SDK shapes derived from: https://code.claude.com/docs/en/agent-sdk/typescript
|
Package types contains handwritten Claude Agent SDK shapes derived from: https://code.claude.com/docs/en/agent-sdk/typescript |
|
claudehook/types/ext/codex
Package codex defines the Codex (OpenAI codex-rs) hook tool input and output shapes that diverge from the Claude Agent SDK tool schemas.
|
Package codex defines the Codex (OpenAI codex-rs) hook tool input and output shapes that diverge from the Claude Agent SDK tool schemas. |
|
filetype
Package filetype provides filetype detection and project-root resolution.
|
Package filetype provides filetype detection and project-root resolution. |
|
harnessctl
Package harnessctl reaches a coding-agent harness from beside it: it recognises which CLI an MCP server is serving and hands back the channel a message reaches that agent through, and, where the harness has one, the feed its state is read from.
|
Package harnessctl reaches a coding-agent harness from beside it: it recognises which CLI an MCP server is serving and hands back the channel a message reaches that agent through, and, where the harness has one, the feed its state is read from. |
|
util/poll
Package poll waits until a target becomes ready: a unix socket accepts a connection, a file exists on disk, or an HTTP endpoint answers with an accepted status, 2xx unless HTTPOption says otherwise.
|
Package poll waits until a target becomes ready: a unix socket accepts a connection, a file exists on disk, or an HTTP endpoint answers with an accepted status, 2xx unless HTTPOption says otherwise. |
|
Package web bundles the compiled Preact single-page app for `crabswarm preview` and exposes it as an fs.FS for the HTTP layer to serve.
|
Package web bundles the compiled Preact single-page app for `crabswarm preview` and exposes it as an fs.FS for the HTTP layer to serve. |
|
scripts/packdist
command
Command packdist packs the vite build output (web/dist) into web/dist.tar.zst, the seekable-zstd tar that web/embed.go embeds.
|
Command packdist packs the vite build output (web/dist) into web/dist.tar.zst, the seekable-zstd tar that web/embed.go embeds. |
Click to show internal directories.
Click to hide internal directories.