Metadata-Version: 2.4
Name: heartofgold
Version: 0.1.0
Summary: A small self-hosted kanban board shared by humans and AI agents, with REST and MCP access.
Author: Daniel Takacs
License-Expression: MIT
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn>=0.30
Requires-Dist: pydantic>=2.7
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: platformdirs>=4.2
Requires-Dist: typer>=0.12
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: markdown-it-py>=3
Requires-Dist: mdit-py-plugins>=0.4
Requires-Dist: linkify-it-py>=2
Requires-Dist: nh3>=0.2.17
Requires-Dist: pillow>=10
Requires-Dist: argon2-cffi>=23
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: mcp>=2.3,<3
Requires-Dist: jinja2>=3.1
Requires-Dist: itsdangerous>=2.2
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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](https://github.com/takacsd/HeartOfGold/blob/main/docs/deployment.md) ·
[client setup](https://github.com/takacsd/HeartOfGold/blob/main/docs/client-setup.md) ·
[agent conventions](https://github.com/takacsd/HeartOfGold/blob/main/docs/agent-conventions.md) ·
[spec](https://github.com/takacsd/HeartOfGold/blob/main/docs/spec.md)

## 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](https://tailscale.com) account.

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

```bash
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.**

```bash
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](https://tailscale.com/download) (distribution packages are often older;
on macOS use the open-source `tailscaled` variant; keep MagicDNS on), log in, then:

```bash
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.

```bash
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`](https://github.com/takacsd/HeartOfGold/blob/main/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](https://github.com/takacsd/HeartOfGold/blob/main/docs/client-setup.md). For Claude Code
on this machine:

```bash
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`](https://github.com/takacsd/HeartOfGold/blob/main/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](https://github.com/takacsd/HeartOfGold/blob/main/examples/heartofgold-backup.timer)
  or cron. Restoring is described in
  [deployment](https://github.com/takacsd/HeartOfGold/blob/main/docs/deployment.md#restore).
- **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.

| Variable | Default | Purpose |
| --- | --- | --- |
| `HEARTOFGOLD_BASE_URL` | `http://127.0.0.1:<port>` | Public URL without a path, e.g. `https://heartofgold.tail1234.ts.net` (may include `:8443`) |
| `HEARTOFGOLD_PORT` | `8000` | Listen port (the server binds to 127.0.0.1; `serve --host` changes that) |
| `HEARTOFGOLD_DATA_DIR` | platform user data dir (`~/.local/share/heartofgold` on Linux) | Database, `files/`, `backups/`, generated secret |
| `HEARTOFGOLD_SECRET_KEY` | generated on first run (stored with mode 0600) | Signs session cookies and CSRF tokens |
| `HEARTOFGOLD_RATE_LIMIT` | `120/minute` | Per credential; `0` disables |
| `HEARTOFGOLD_MAX_UPLOAD_MB` | `10` | Per-file REST upload limit (MCP uploads: 256 KB) |
| `HEARTOFGOLD_MAX_STORAGE_MB` | `2048` | Total attachment storage |
| `HEARTOFGOLD_LOG_LEVEL` | `info` | JSON log lines on stdout |

## 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

```bash
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`](https://github.com/takacsd/HeartOfGold/blob/main/docs/DECISIONS.md).

## License

MIT
