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 < flags; these keys
are file-only and are not settable via environment variables):
| Key | Default | Meaning |
|---|---|---|
preview.addr |
0.0.0.0:6419 |
TCP listen address of the preview HTTP server. |
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. |
|
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. |
|
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 handler, 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 handler, 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). |
|
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 an opt-in 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 an opt-in 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. |
|
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. |
|
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. |
Click to show internal directories.
Click to hide internal directories.