Understand how you and your AI agents actually work.
Spantail is an open-source platform for recording human and AI work with as little overhead as
possible — ideally none — then sharing and reviewing it in seconds. Built for the era of
human–AI collaboration: humans log work in a few keystrokes, AI coding agents stream their own
sessions in automatically, and the unified timeline becomes any report you need — daily, weekly,
monthly. Built AI-first: every operation is available to humans (web, CLI) and AI agents (MCP)
through the same API.
Features
- Low-overhead capture — work entries are a date, duration, description, and tags, with optional start/end times — built for fast daily logging. AI coding-agent work is captured automatically, with no manual entry.
- AI agent sessions — register an AI coding agent and its sessions stream in automatically: per-session duration and token usage land on the same timeline as human work. The Claude Code plugin captures sessions per turn while conversation bodies stay on your machine.
- GitHub integration — log work without leaving GitHub: comment
@spantail 2h yesterday on an issue or pull request and the entry lands on the project that repository maps to. Each instance registers its own private GitHub App via GitHub's manifest flow, so credentials go straight from GitHub to your instance and no central App sits in between. See GitHub integration.
- Workspaces — organize work by department, team, or client organization. Projects live under workspaces. One deployment serves one company; this is not a multi-tenant SaaS.
- Unified reports — no hardcoded report types. A report is a Markdown + Liquid template applied to filters you choose freely: any combination of workspaces, projects, users, and date range — including across workspaces. Built-in templates cover daily, weekly, and monthly reports.
- Safe report sharing — share an immutable report snapshot via an expiring, revocable link with an optional passcode. Viewers don't need an account — share with clients, stakeholders, or anyone outside your instance.
- Collaborate on reports — discuss a shared report inline with Markdown comments and GitHub-style emoji reactions, keeping the conversation next to the report instead of in email.
- Keyboard-first — the web UI is driven without the mouse: single-key shortcuts cover creating, moving through lists, opening, and bulk actions. See keyboard shortcuts.
- AI-first API — a built-in MCP server (remote Streamable HTTP, or local stdio via the CLI) and a CLI let AI agents and scripts log work and pull reports through the same REST API the web UI uses.
- English / Japanese — fully localized UI and documentation.
Architecture
Spantail runs entirely on Cloudflare:
- Workers — a single Worker serves the REST API (
/api/v1), the MCP endpoint (/mcp), shared report views, and the SPA static assets
- D1 — primary database
- R2 — uploaded images (user avatars, workspace logos)
Backend is Hono with Drizzle and Better Auth. Frontend is a React SPA built with Vite, TanStack Router/Query, and shadcn/ui.
Three docs go deeper:
- Data model — the resources Spantail stores and how they relate
- Permissions — the role-based permissions and resource visibility model
- Security — the Spantail-specific security properties and standing threats
Monorepo
| Path | Description |
|---|
apps/web | Main application (Worker: API + MCP + SPA) |
apps/docs | Documentation site (Astro Starlight, en/ja) |
packages/core | Domain logic, Zod schemas, report engine |
packages/db | Drizzle schema, migrations, queries |
packages/sdk | Typed API client |
packages/cli | spantail CLI (includes spantail mcp stdio server) |
plugins/claude-code | Claude Code plugin: telemetry hooks, work-logging and reporting skills |
Getting started
Prerequisites: Node.js 24+, pnpm 11+, a Cloudflare account, and wrangler v4.
git clone https://github.com/spantail/spantail.git
cd spantail
pnpm install
# create local env vars
cp apps/web/.dev.vars.example apps/web/.dev.vars
# apply migrations to the local D1 emulator and start the dev server
pnpm db:migrate:local
pnpm dev
pnpm dev runs the SPA and the Worker together on the Cloudflare Vite plugin, with local emulation of D1.
Self-hosting
Spantail is designed to be deployed to your own Cloudflare account. The recommended path is a
fork connected to Cloudflare Workers Builds:
- Fork this repo and create a D1 database (
spantail-db) and an R2 bucket (spantail-uploads) in
your Cloudflare account.
- Create a Worker from your fork — root directory
apps/web, deploy command pnpm run deploy:ci,
build variable D1_DATABASE_ID set to your D1 database ID.
- Set the
BETTER_AUTH_SECRET Worker secret (≥ 32 chars). Without it the Worker fails closed.
The first build applies migrations and deploys; the first person to sign up becomes the admin.
Upgrading is GitHub's Sync fork button — Workers Builds re-runs migrate + deploy automatically.
A manual Wrangler flow is also available.
See the full self-hosting guide, including required
secrets and cost notes.
The reference Claude Code hook sends telemetry, not transcripts
It parses the transcript locally and sends compact telemetry — token counts, timing, and context
such as the model, git branch, and working directory — not your conversation transcripts or
source code, so conversation bodies never leave your machine. The
plugin's privacy notes list the exact fields. (What reaches
Spantail is only ever what a client sends, so other integrations are only as bounded as what
they send.)
Whatever a client does record, though — descriptions, notes, tags, and any event payload it
sends — is stored verbatim and can appear in reports, public share links, and Send-to
deliveries. Treat it as potentially secret-bearing: don't put secrets in those fields, and
don't emit secrets into agent logs. See docs/security.md (§2).
CLI & MCP
spantail auth login # store an API token
spantail log "Implemented report engine" --project core --duration 2h
spantail entries list --from 2026-06-01
spantail report create --template default --workspace acme --range last-month
spantail mcp # stdio MCP server for AI clients
AI clients that support remote MCP can connect directly to https://your-instance/mcp with an API token.
To record Claude Code sessions, register an agent in Spantail and install the
Claude Code plugin (/plugin marketplace add spantail/spantail), which reads
each turn's transcript locally and posts only compact telemetry.
Development
docs/conventions.md is the contributor's reference: the full command
list (tests, lint, typecheck, migrations, seeding), the repository conventions, the architecture
invariants, and the Definition of Done.
For manual checks, the run-demo Claude
Code skill is a convenient way to seed demo data and drive the app in a
browser (optional — it also documents the recipe for doing it by hand).
Contributing
Spantail is built in the open, and contributions of every size are welcome.
- Shape the direction — bring ideas, questions, and half-formed proposals to
Discussions. Settling the what there keeps
issues focused on agreed work.
- Report a bug or request a feature — open an
issue. Small, obvious fixes don't need
a discussion first.
- Send a pull request —
good first issue
is a good place to start.
CONTRIBUTING.md covers the workflow; docs/conventions.md
covers the conventions a change must meet.
License and scope
MIT — this repository in full, permanently.
Spantail is open core. An Enterprise Edition, which adds organizational governance and built-in
automation on top of this codebase, is distributed separately under its own commercial license.
docs/open-core.md explains where that line runs, the principle behind it,
and what we promise will never leave the core. Native desktop and mobile apps are out of scope
for this repository.
