human

https://gethuman.sh

human is your team's AI dev rig — everything your AI development needs, best of breed, already wired. Trackers, docs, designs, analytics, a secure sandbox, and the lifecycle workflow, in one open-source install, configured the right way around the coding agent you already run. Nothing to research, assemble, or keep up with.

• Secure by default — outbound firewall, secret-redacting filesystem, vault-resolved credentials, isolated devcontainer. The AI works on your code, never sees your tokens.
• Saving Tokens — structural code navigation and signal-extracted tracker data: up to 95% fewer tokens than raw APIs or MCP servers.
• Context engineering — connectors for every source (trackers, Notion, Figma, Amplitude) with one cross-source search and codebase indexing, so the AI builds from real requirements, not guesses.
• Best of breed, one install — the best tool in every category, integrated and tested together. No MCP hunting, one credential system, we keep it current.
• You in control — live dashboard of agents, tokens, and pipeline state, guardrails and policy rules, and a full audit trail.
• Automatic development — lifecycle skills from ideate to review, plus optional autonomous bug-fixing. Turn autonomy up when you're ready.

Architecture

Install

curl -sSfL gethuman.sh/install.sh | bash

Or with Homebrew:

brew install --cask gethuman-sh/tap/human

Since v0.20.0 human ships as a Homebrew cask (previously a formula). If you installed an earlier version, brew upgrade will not cross the formula→cask boundary — reinstall once to migrate:

brew uninstall human && brew install --cask gethuman-sh/tap/human

Or with mise:

mise use -g github:gethuman-sh/human

Or with Go:

go install github.com/gethuman-sh/human@latest

Or add as a devcontainer Feature:

{ "features": { "ghcr.io/gethuman-sh/treehouse/human:1": {} } }

Quick start

human init

The wizard configures your services, generates devcontainer.json with daemon, Chrome proxy, firewall, and installs the Claude Code integration. Set the API tokens it prints, then start:

human daemon start
devcontainer up --workspace-folder .

What's included

Module features

Each module ships a short README.md describing what it does for you, in plain language.

Issue trackers & forges

• Issue Trackers — Jira, Linear, GitHub, GitLab, Shortcut, Azure DevOps, ClickUp
• Code Forges — open pull requests (GitHub)
• Marker Protocol — post/read the structured [human:*] pipeline handoff comments
• Pipeline Runtime — shared state, race-free finding IDs, and cleanup for multi-agent scans

Docs, design & analytics

• Knowledge & Insights — Notion docs, Figma designs, Amplitude analytics

Messaging & agents

• Messaging — Slack and Telegram send/receive
• Message Dispatch — route chat messages to idle agents
• Code Navigation — index code; def/refs/call-graph/impact for agents
• AI Developer Agents — run Claude Code in isolated containers
• Claude Code Integration — skills, agents, and live monitoring
• Activity Statistics — rolling record of agent tool usage

User interfaces

• Workflow Board (desktop) — drag-to-trigger pipeline board that builds, reviews, and ships (Wails)
• Project Starters — scaffold empty directories from starter templates

Infrastructure & security

• Audit Trail — structured, queryable record of every agent action against trackers
• Background Daemon — holds credentials, answers commands fast, runs the preflight doctor (human doctor, board health LED)
• Dev Containers — reproducible sandbox for agents
• HTTPS Proxy — filter outbound agent traffic by domain
• Chrome Bridge — drive host Chrome from a container
• OAuth Sign-In — handle localhost OAuth callbacks
• Browser Opener — open links in your default browser
• Secret-Redacting Filesystem — hide secrets from agents
• Secret Vault — resolve 1pw:// references at startup

Core & utilities

• Project Configuration — .humanconfig.yaml and credentials
• Cross-Tracker Search — local full-text index over all issues
• Git Repository — detect forge and project from git
• Tracker Connections — shared networking for every backend
• Setup Wizard — guided human init onboarding
• Update Notifications — background new-release checks
• Per-Request Settings — isolated settings per daemon request
• Command Flags — consistent CLI option parsing
• Platform Detection — adapt behavior per operating system
• CLI Banner — the gradient human startup banner

Dashboard

human tui

The TUI shows running Claude Code instances, token usage per 5-hour window, daemon status, and connected containers — all in one view. It auto-starts the daemon if needed.

Agent spawn (a) and dispatch (⏎) require tmux on the host and that the TUI itself runs inside a tmux session. Browsing issues and every other view work without it. If tmux is missing, install it (brew install tmux on macOS, sudo apt-get install tmux on Debian/Ubuntu, or your distro's package). To run the TUI inside a session, launch it as:

tmux new -s human "human tui"

The TUI runs a launch-time preflight and shows a banner with the exact command to run if either check fails.

CLI usage

Quick commands auto-detect the tracker from the key format. Use --table for human-readable output.

human get KAN-1                        # get an issue
human list --project=KAN               # list issues
human status KAN-1 "Done"             # set status
human jira issue start KAN-1           # transition + assign
human jira issue edit KAN-1 --title "New title"
human jira issue comment add KAN-1 "Shipped"

human pr create --head fix-login --title "Fix login" --body "Closes #42"  # open a PR; forge + repo derived from the git origin remote

human search "retry logic"             # cross-tracker search
human notion search "quarterly report" # Notion
human figma file get <file-key>        # Figma
human amplitude events list            # Amplitude
human telegram list                    # Telegram

Devcontainer / Remote mode

Quick start: Use the treehouse devcontainer Feature — it installs human, sets up OAuth browser forwarding, and optionally configures the HTTPS proxy. Add it to your devcontainer.json and you're done.

AI agents running inside devcontainers need access to issue trackers, Notion, Figma, and Amplitude, but credentials should stay on the host. The daemon mode splits human into two roles: a daemon on the host (holds credentials, executes commands) and a client inside the container (forwards CLI args, prints results). You need human installed on both sides: on the host (via Homebrew, curl, etc.) to run the daemon, and inside the container (via the devcontainer Feature) as the client. It's the same binary — the mode is determined by the HUMAN_DAEMON_ADDR environment variable.

On the host:

human daemon start          # prints token, listens on :19285
human daemon token          # print token for copy/paste
human daemon status         # check if daemon is reachable

In devcontainer.json, add the devcontainer Feature to install human and configure the daemon connection:

{
  "features": {
    "ghcr.io/gethuman-sh/treehouse/human:1": {}
  },
  "forwardPorts": [19285, 19286],
  "remoteEnv": {
    "HUMAN_DAEMON_ADDR": "host.docker.internal:19285",
    "HUMAN_DAEMON_TOKEN": "<paste from 'human daemon token'>",
    "HUMAN_CHROME_ADDR": "host.docker.internal:19286",
    "BROWSER": "human-browser"
  }
}

Inside the container, all commands work transparently:

human jira issues list --project=KAN       # forwarded to host daemon
human figma file get ABC123                # forwarded to host daemon
human notion search "quarterly report"     # forwarded to host daemon

Chrome Bridge

When using Claude Code inside a devcontainer, the Chrome MCP bridge needs a Unix socket that Claude can discover. The chrome-bridge command creates this socket and tunnels traffic to the daemon on the host.

human chrome-bridge                        # daemonizes, prints PID and socket path
claude                                     # runs immediately after

The bridge requires HUMAN_CHROME_ADDR and HUMAN_DAEMON_TOKEN environment variables (included in the devcontainer.json example above). Use --foreground for debugging. Logs are written to ~/.human/chrome-bridge.log.

OAuth / browser forwarding

Tools like Claude Code require OAuth authentication, which needs to open a browser on the host. The treehouse Feature handles this automatically by creating a human-browser symlink and setting BROWSER=human-browser. When Claude Code triggers OAuth, human-browser forwards the request to the daemon, which opens the real browser on the host and relays the callback back to the container.

If you're not using the treehouse Feature, add "BROWSER": "human-browser" to your remoteEnv and ensure the human-browser symlink exists in the container (pointing to the human binary).

HTTPS proxy

The daemon includes a transparent HTTPS proxy on port 19287 that filters outbound traffic from devcontainers by domain. It reads the SNI from TLS ClientHello — no certificates needed, no traffic decryption.

Configure allowed domains in .humanconfig.yaml:

proxy:
  mode: allowlist    # or "blocklist"
  domains:
    - "*.github.com"
    - "api.openai.com"
    - "registry.npmjs.org"

• allowlist: only listed domains pass, everything else blocked
• blocklist: only listed domains blocked, everything else passes
• No proxy: section: block all (safe default)

Enable in devcontainer.json using the treehouse devcontainer Feature:

{
  "features": {
    "ghcr.io/gethuman-sh/treehouse/human:1": {
      "proxy": true
    }
  },
  "capAdd": ["NET_ADMIN"],
  "remoteEnv": {
    "HUMAN_DAEMON_ADDR": "host.docker.internal:19285",
    "HUMAN_DAEMON_TOKEN": "<paste from 'human daemon token'>",
    "HUMAN_CHROME_ADDR": "host.docker.internal:19286",
    "HUMAN_PROXY_ADDR": "host.docker.internal:19287",
    "BROWSER": "human-browser"
  },
  "forwardPorts": [19285, 19286],
  "postStartCommand": "sudo human-proxy-setup"
}

See the treehouse README for full setup instructions.

Claude Code skills

Install the Claude Code skills and agents into your project:

human install --agent claude

This writes skill and agent files to .claude/ in the current directory. Re-run after upgrading human to pick up changes.

# Full pipeline in one command
/human-sprint "add rate limiting to the API"

# Or step by step
/human-ideate "add rate limiting"  # challenge idea, create PM ticket
/human-plan 42                     # attach an engineering plan (separate ticket or plan comment, per topology)
/human-execute HUM-43              # implement the plan
/human-review HUM-43               # review changes

All outputs are saved to .human/ (plans, reviews, done reports, bug analyses, security audits, health reports).

Autonomous bug fixing

/human-autofix runs the full bug-fix pipeline autonomously — pointed at a bug ticket, it never asks the user a question:

/human-autofix SC-86               # triage, root-cause, fix, verify, review — a passing review merges the PR

It moves through seven phases: triage and reproduce the bug down to its root cause, gate on the verdict, plan a regression-test-first fix (attached as a linked engineering ticket in split topology, or as a [human:plan] comment on the bug ticket itself with a single tracker), write the failing regression test then fix the root cause and push, verify the fix is "done done", chain into a review by the reviewer agent, and — on a passing verdict — deploy: open the PR, gate on CI, and merge.

Triage returns one of three verdicts, posted as a [human:bug-verdict] comment on the ticket — the ticket's permanent root-cause record, opening with a plain-language explanation a non-engineer can follow, then the minimal reproduction, the cause chain (symptom → proximate cause → underlying cause, with file:line evidence), the regression window (the commit that introduced the defect, when it can be found), and any sibling occurrences of the same defect pattern elsewhere in the codebase:

• confirmed — the bug is reproduced; the pipeline proceeds to fix it.
• not-a-bug — the ticket is closed or reclassified, with no code changes.
• undetermined — the ticket is left open, with no code changes.

A not-a-bug or undetermined verdict is a successful terminal outcome, not a failure: the run posts a [human:no-fix-needed] marker and stops cleanly. On the board this surfaces the card as resolved ("no fix needed"), never as a red/failed run — the failure watcher recognizes the marker instead of mistaking the missing review handoff for a crash and looping forever re-triaging.

Only a confirmed bug that passes the verification gate moves on. To run the quality suite exactly once per fix (SC-782), the tiers are split: the fixer iterates on the fast test+lint tier to go green, and the verify gate runs the one authoritative full-suite pass — regression test fails before the fix, passes after, the full suite green — recording that result as a commit-bound ## Evidence block (branch/commit/command/result) on the ticket. The fix lands on an autofix/ branch with commits referencing the ticket trail (both the PM and engineering keys in split topology, the single bug key otherwise), and a [human:ready-for-review] comment is posted on the PM ticket carrying the branch: and commits: lines — plus an engineering: line in split topology; when that line is absent, reviewers review the PM ticket itself.

The run then chains into the review, exactly like the kanban flow chains a clean build: the human-reviewer agent reviews the branch against the plan and acceptance criteria, trusts the recorded full-suite Evidence when it is bound to the reviewed commit (re-running only the tests its own findings put in doubt, instead of repeating the whole suite), and posts the verdict as a [human:review-complete] comment. A pass (or pass with notes) drives the same deploy pipeline as the board's Deploy stage — PR opened, CI gate, merge, branch deleted, ticket moved to done, [human:deployed] posted. A fail gets one rework cycle (fixer → verify → re-review); if it still fails, the run stops honestly with the handoff standing for a human and no PR merged. When autofix runs as a board stage agent (dropped on the Bugs pane's Fix column), the review runs inline in the same warm implementation container (SC-782) — one container startup, not two — so the board shows one continuous run instead of two sequential containers; only the deploy is left to the Bugs pane's Deploy button, which ships the reviewed fix. CI remains the final gate on every merge.

The whole trail lives on the trackers — root-cause comment, plan (engineering ticket or plan comment), review verdict, deploy markers; the only .human/ working file is the reviewer's report. If the build, tests, review, or CI gate aren't green, the pipeline stops and reports honestly rather than claiming success.

Configuration

The fastest way to get started:

human init

The interactive wizard lets you pick trackers and tools, then writes .humanconfig.yaml and prints the environment variables to set.

Alternatively, configure manually:

# Issue trackers
jiras:
  - name: work
    url: https://work.atlassian.net
    user: [email protected]
    key: your-api-token

githubs:
  - name: oss
    token: ghp_abc123

linears:
  - name: work
    projects:
      - ENG

# Tools
notions:
  - name: work
    token: ntn_abc123

figmas:
  - name: design
    token: figd_abc123

amplitudes:
  - name: product
    url: https://analytics.eu.amplitude.com

# Messaging
telegrams:
  - name: bot
    allowed_users:
      - 12345678

# Outbound proxy
proxy:
  mode: allowlist
  domains:
    - "*.github.com"

Tokens can also be set via environment variables using the pattern <TRACKER>_<NAME>_TOKEN (e.g. JIRA_WORK_KEY, NOTION_WORK_TOKEN, FIGMA_DESIGN_TOKEN, AMPLITUDE_PRODUCT_KEY + AMPLITUDE_PRODUCT_SECRET).

See documentation.md for full configuration details.

Build

make build

Desktop app (workflow board)

The desktop GUI is the interactive workflow board with five columns (Ideas → Product backlog → Engineering backlog → Code → Ready to Deploy) plus a terminal Deploy drop zone: every column names a state that is true of each card in it, and dragging a card forward launches that transition's human agent. Code holds the whole build-and-review cycle — dropping an engineering-backlog card there launches the executor, and when the build lands the review starts automatically, no gesture. A passing review releases the card into Ready to Deploy on its own; a failing verdict pins it in Code with a warning icon and the findings as a ticket comment (re-drop it on Code to rebuild against them). Dropping a reviewed card on Deploy ships it: branch pushed, PR opened, merged once CI is green, ticket closed — the card leaves the board, which shows only work in flight. On merge-deploy platforms (Scalingo, Heroku, Vercel, …) that drop puts the change in production. Right-click a card for Close ticket / Open in tracker; Product-backlog cards also offer Create mocks (UI mockups for the ticket via /human-mockups), which becomes View mocks once the set exists. The Ideas queue is an idea space — one rounded rectangle five invisible lanes wide: drag ideas left or right to sort looser ones left and concrete ones right — placement is saved locally, never on the ticket. Its + quick-captures a title-only ticket labeled human/idea into the leftmost sub-column; dragging an idea onto the Product backlog opens guided ideation that evolves the same ticket in place (same key, idea label removed). It runs on macOS, Windows and Linux.

It must be built via the Wails CLI, never plain go build ./desktop/ — Wails v2 requires build tags that only wails build (or wails dev) injects, and the whole desktop/ package is behind a wailsapp build tag so the default make build/make check stay green on a plain toolchain.

Prerequisites (per-OS webview toolchain — see docs/desktop-app.md):

make desktop-deps   # installs the pinned Wails CLI
# macOS:   xcode-select --install
# Linux:   sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.1-dev
# Windows: WebView2 runtime (preinstalled on current images)

Then build (current OS only — cgo backends cannot be cross-compiled):

make desktop

CI builds all three OSes on a native-runner matrix (.github/workflows/desktop.yml). See docs/desktop-app.md for details, the regression guard, and why go build is not a valid smoke test.

Star History