hypergumbo-tracker

Structured work tracker for AI agent governance. Append-only YAML op-logs that are git-merge-safe, causally ordered, and support field-level access control. Agents get structured task selection; humans get locks, tier control, a TUI, and a web interface.

See CHANGELOG.md for release history.

Setup

1. Install

Install the tracker into your project's virtual environment:

# As either user (whoever owns the venv)
source .venv/bin/activate   # or wherever your venv lives
pip install hypergumbo-tracker

2. Create an agent user

The tracker uses os.getuid() to distinguish agents from humans. Run the agent as a separate OS user for OS-enforced access control:

# As the human user (needs sudo)
sudo useradd -m myproject_agent
sudo groupadd project-dev
sudo usermod -aG project-dev yourname
sudo usermod -aG project-dev myproject_agent

Important: Group membership doesn't take effect in existing shells. Either log out and back in, or run newgrp project-dev in your current session.

If the repo lives under the agent's home directory, the human user also needs traversal access:

# As the human user (needs sudo)
sudo chmod o+rx /home/myproject_agent

3. Run the wizard

# As the human user (recommended — can auto-fix config ownership)
cd /path/to/your-repo   # must be the repo root
htrac setup

This creates directories, configures git plumbing (merge=union, textconv), copies the config template, sets file permissions, and reports anything that needs attention. It's idempotent — run it again anytime to diagnose issues.

The wizard handles common pitfalls automatically:

• Running as agent? Prompts to switch to the human user and prints ready-to-paste setup commands (venv activation, htrac setup, group fixes).
• Cross-user repo ownership? Auto-adds safe.directory to git config.
• .git/config not writable? Falls back to --global for textconv.
• Two-user group misconfigured? Reports specific problems (missing group-write, missing setgid, user not in group) with fix commands that include the detected group name.
• Config owned by wrong user? Auto-fixes when run as human.

Set group ownership on the directories the wizard created so both users can write to ops files:

# As the human user (needs sudo)
sudo chgrp -R project-dev .agent/tracker .agent/tracker-workspace
sudo chmod -R g+rws .agent/tracker/.ops .agent/tracker-workspace .agent/tracker-workspace/.ops .agent/tracker-workspace/stealth

Verify the human user can write:

# As the human user (must have run newgrp project-dev or started a new session)
touch .agent/tracker-workspace/.ops/test && rm .agent/tracker-workspace/.ops/test

If you get "Permission denied", check that newgrp project-dev was run (or start a new login session).

Note: Git does not track file ownership or group permissions. After a fresh git clone, you must re-run htrac setup and repeat the chgrp/chmod commands above.

You now have:

• htrac — CLI for agents (htrac ready, htrac add, htrac update, ...)
• htrac tui — interactive terminal UI for humans
• htrac setup — re-runnable setup wizard

Permission testing

For two-user setups, verify the permission boundary end-to-end with the Permission Test Playbook. The playbook exercises human-only operations (lock, stealth, delete), agent restrictions, and filesystem permission checks. If tests fail, re-run htrac setup (see Run the wizard above) and follow its fix instructions.

Agent usage

These commands are run as the agent user (e.g. myproject_agent). The tracker records by: agent on each operation, and human-only commands (lock, stealth, discuss --clear) are blocked.

htrac ready                    # What should I work on?
htrac check-messages           # Any unread human messages?
htrac clusters                 # Predicted clusters of the open items (TF-IDF kNN)
htrac update :1 --status in_progress   # Claim the top item
htrac add --kind work_item --title "Add Dart analyzer" --priority 1
htrac update INV-lusab --status done --note "Fixed in PR #42"
htrac show INV-lusab           # Full item details
htrac list --status todo_hard  # Filtered listing
htrac discuss INV-lusab "Root cause confirmed in parser.py"
htrac deps INV-lusab           # Dependency graph view
htrac batch < commands.txt     # Bulk operations

Positional aliases: htrac ready and htrac list assign shortcuts :1, :2, etc. to their output rows. Use them in the next command (e.g. htrac update :1 --status in_progress). Aliases reset after any non-list command.

--note on update is shorthand for a follow-up discuss entry — e.g. htrac update WI-foo --status done --note "Fixed in PR #42" updates status and records why in one command.

Use htrac <command> --help for all options. Use --json on any command for machine-readable output.

Human usage

These commands are run as the human user (e.g. yourname). The tracker records by: human on each operation, enabling human-only commands that agents cannot access.

htrac tui                      # Interactive terminal UI
htrac lock INV-lusab status    # Prevent agent from changing status
htrac stealth WI-nipam         # Hide item from git (human-only)
htrac discuss INV-lusab --clear  # Clear discussion (human-only)

The TUI supports three layouts (compact/standard/wide) based on terminal size. Keybindings: q quit, f filter, d discuss, m move tier, n new item, e edit, l lock/unlock, S screenshot. Screenshot mode supports annotation with rectangles (R + drag), arrows (A + drag), and numbered text labels (L + click).

Both users can read all items — the access control only applies to writes.

Web interface

htrac serve starts a local web server for browser-based access:

htrac serve                    # Foreground on 127.0.0.1:7380
htrac serve --background       # Daemonize
htrac serve --status           # Check if running
htrac serve --stop             # Shut down

The server exposes a REST API (/api/items, /api/ready, create/update/discuss endpoints) and a WebSocket (/ws) for real-time state sync. A filesystem watcher detects CLI/TUI ops file changes and auto-broadcasts to all connected clients.

Auth: WebAuthn/FIDO2 hardware key authentication (ES256, RS256) and bcrypt password verification. Per-credential rate limiting with exponential backoff. Configure in config.yaml under auth.

The web frontend (Vite + TypeScript + BlockSuite) lives in packages/htrac-frontend/. It uses a service worker for cache-first loading and reconnects to WebSocket with exponential backoff.

Core concepts

Items have an ID, kind, status (todo_hard → done), priority (0–4, lower = higher), and optional fields, tags, and discussion.

IDs are content-hash proquints: INV-lusab-bired, WI-nipam-fotil — deterministic, collision-resistant, pronounceable.

Kinds define item shape. Defaults: invariant (INV), meta_invariant (META), work_item (WI). Add custom kinds in config.yaml.

Tiers control visibility:

Move items between tiers: promote, demote, stealth, unstealth.

Dependencies: X.isbefore = [Y] means finish X before Y. The ready command respects this.

Auto-sync: When pending ops exceed a threshold (default 40 lines), the tracker automatically commits, pushes, polls CI, and merges — keeping tracker state synced across branches without manual intervention.

Stop hook integration

Three commands for autonomous-agent stop hooks:

# Called by the stop hook (runs as the agent user)
htrac count-todos              # Number of blocking items (0 = ok to stop)
htrac hash-todos               # SHA-256 fingerprint (circuit-breaker detection)
htrac guidance                 # Generate guidance file for the agent

Example hook snippet:

count=$(htrac count-todos 2>/dev/null || echo 0)
if [ "$count" -gt 0 ]; then
  echo "BLOCKED: $count items remain"
  exit 1
fi

Pre-commit integration

# In .githooks/pre-commit:
staged_ops=$(git diff --cached --name-only -- '*.ops')
if [ -n "$staged_ops" ]; then
  htrac validate $staged_ops --check-locks --strict || exit 1
fi

htrac setup also configures the git textconv driver so git diff shows compiled item state instead of raw YAML.

Configuration

Config loading order: config.yaml (gitignored, yours to edit) → config.yaml.template (tracked, shared) → built-in defaults.

htrac setup copies the template to config.yaml if it doesn't exist and ensures it's owned by the human user (governance settings shouldn't be agent-writable). See the template file for the full schema. Key sections:

• kinds — item types with optional fields_schema
• statuses — lifecycle states
• stop_hook — which statuses block agent stopping, scope (all vs workspace)
• actor_resolution.agent_usernames — fnmatch patterns (default: ["*_agent"])
• lamport_branches — branches for clock sync and cross-branch locks

Fork workflow

# As the agent user (in your fork)
htrac fork-setup               # Sets scope to workspace-only

This makes count-todos and hash-todos ignore upstream canonical items so they don't block your agent. Items you create default to workspace; the upstream maintainer can promote them after merge.

License

Mozilla Public License 2.0. Other hypergumbo packages are AGPL-3.0-or-later. See the repository root LICENSE and CONTRIBUTING.md.