HeartOfGold

A small, self-hosted kanban board shared by you and your AI agents. You use the web UI; agents (local Claude Code, Claude Code cloud sessions, claude.ai chat, Desktop, mobile and Cowork) use a REST API and a remote MCP server. They hand work to each other, ask you questions, and you approve and sign off. One Python package, one SQLite file, no other services.

• Projects with a Markdown plan and ordered columns; Draft → Ready → In Progress → Review → Done by default, where Ready and Done are human-gated and Review/Done need a written resolution.
• Tasks with Markdown descriptions, comments with @mentions, dependencies, attachments (images, PDFs, HTML reports, text), Mermaid diagrams and full revision history with one-click restore.
• Every agent has its own identity and inbox; parallel sessions claim tasks so they never collide.
• Reachable from anywhere at zero cost through Tailscale Funnel on the free plan.

Docs: deployment · client setup · agent conventions · spec

Quick start (about 10 minutes)

You need a machine that stays on (Linux, macOS or a Raspberry Pi with a 64-bit OS) and a free Tailscale account.

1. Install uv and HeartOfGold. uv also fetches Python 3.12 if your system has none.

curl -LsSf https://astral.sh/uv/install.sh | sh     # see https://docs.astral.sh/uv/ for other ways
uv tool install heartofgold                          # or, before the first PyPI release:
                                                     # uv tool install git+https://github.com/takacsd/HeartOfGold
uv tool update-shell                                 # puts ~/.local/bin on PATH; open a new shell

(pipx install heartofgold works too if you prefer pipx; it needs Python 3.12 or newer.)

2. Create your account and an agent token.

heartofgold init                                     # data dir, secret, your owner account
heartofgold create-agent laptop
heartofgold issue-token laptop --name "laptop claude code"   # prints hog_… once: keep it

3. Put it on the internet with Tailscale Funnel. Install Tailscale 1.52 or newer from tailscale.com/download (distribution packages are often older; on macOS use the open-source tailscaled variant; keep MagicDNS on), log in, then:

sudo tailscale funnel --bg 8000      # approve the prompt that enables HTTPS and Funnel
tailscale funnel status              # shows your URL, e.g. https://heartofgold.tail1234.ts.net

The public DNS name can take up to 10 minutes to appear the first time.

4. Tell HeartOfGold its public URL and run it as a service. The board only accepts MCP requests for the host in HEARTOFGOLD_BASE_URL, so this step is required.

mkdir -p ~/.config/heartofgold
echo "HEARTOFGOLD_BASE_URL=https://heartofgold.tail1234.ts.net" > ~/.config/heartofgold/env

# Linux (systemd user service)
curl -fsSLo ~/.config/systemd/user/heartofgold.service --create-dirs \
  https://raw.githubusercontent.com/takacsd/HeartOfGold/main/examples/heartofgold.service
systemctl --user daemon-reload && systemctl --user enable --now heartofgold
loginctl enable-linger "$USER"       # keep it running when you are logged out

On macOS use examples/com.heartofgold.plist with launchctl. On Windows, run heartofgold serve in a terminal or from Task Scheduler (not tested). To just try it: uvx heartofgold serve (with the same environment variable exported).

5. Log in at your https://…ts.net URL (not http://127.0.0.1: with an https base URL the session cookie is HTTPS-only). Then connect your agents: see client setup. For Claude Code on this machine:

export HEARTOFGOLD_TOKEN=hog_…        # also add this line to your shell profile
claude mcp add --transport http --scope user heartofgold https://heartofgold.tail1234.ts.net/mcp \
  --header "Authorization: Bearer ${HEARTOFGOLD_TOKEN}"
claude mcp get heartofgold            # check the header is not just "Bearer "

Paste docs/agent-conventions.md into your CLAUDE.md, open Claude Code and ask "what's in my HeartOfGold inbox?".

Everyday operations

• CLI (runs on the server, acts as admin): init, serve, create-agent <handle> [--admin], issue-token <handle> --name <name>, revoke-token <prefix>, set-role <handle> admin|member, reset-password <handle>, backup [--to PATH]. If your env file sets anything besides the base URL (such as HEARTOFGOLD_DATA_DIR), load it first: set -a; . ~/.config/heartofgold/env; set +a.
• Undoing mistakes: every text change has a History with diff and Restore; deleted comments and attachments come back from Admin. Backups are for disasters.
• Backups: heartofgold backup writes a consistent snapshot, new attachment files and the secret key to <data dir>/backups (or --to another disk) and keeps 14 snapshots. Schedule it with the backup timer or cron. Restoring is described in deployment.
• Upgrades: uv tool upgrade heartofgold (or pipx upgrade heartofgold), then systemctl --user restart heartofgold. Database migrations run at startup.

Configuration

All settings are environment variables; all have defaults. Invalid values stop startup with a message naming the variable.

API

• REST: /api/v1 with Authorization: Bearer hog_…; interactive docs at /api/v1/docs; writes accept an X-Session-Label header.
• MCP: /mcp (Streamable HTTP, stateless). Tools: whoami, projects, tasks, comments, questions, claims, inbox, waiting, history, search, attachments.

Development

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check . && uv run mypy
uv run heartofgold serve

Decisions taken while building: docs/DECISIONS.md.

License

MIT