human

README

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

Category	Services
Issue Trackers	Jira, GitHub, GitLab, Linear, Azure DevOps, Shortcut
Docs & Knowledge	Notion (search, pages, databases), ClickUp (Docs, wikis, knowledge base)
Design	Figma (files, components, comments, export)
Analytics	Amplitude (events, funnels, retention, cohorts)
Messaging	Telegram (bot messages as task inbox), Slack (notifications)
Infrastructure	Daemon mode, HTTPS proxy/firewall, Chrome Bridge, OAuth forwarding
Governance	Declarative policy rules in .humanconfig (block/confirm agent operations)
Skills	Ideate, sprint, ready, brainstorm, plan, execute, review, done, findbugs, security
Dashboard	TUI with agent monitoring, token usage, tracker issues, pipeline state
Search	Cross-tracker and Notion full-text index

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)

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 5-stage pipeline board (Wails)

Infrastructure & security

• Audit Trail — structured, queryable record of every agent action against trackers
• Background Daemon — holds credentials, answers commands fast
• 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.

Skill	Description
/human-ideate	Challenge an idea with forcing questions and create a ready PM ticket
/human-sprint	Run the full pipeline in one command: ideate → plan → execute → review
/human-ready	Evaluates a ticket against a Definition of Ready checklist
/human-brainstorm	Explores the codebase and generates 2-3 implementation approaches
/human-plan	Fetches a ticket and produces a structured implementation plan
/human-bug-plan	Analyzes a bug ticket for root cause and writes a fix plan
/human-autofix	Autonomously triages, fixes, verifies, and opens a PR for a bug end to end — the whole trail recorded on the tracker
/human-execute	Loads a plan, executes step by step, runs a review checkpoint
/human-review	Diffs the current branch against acceptance criteria
/human-findbugs	Multi-agent pipeline to find logic errors, race conditions, and security issues
/human-security	Deep security audit with attack chain analysis and OWASP Top 10 coverage
/human-gardening	Multi-agent pipeline for codebase health analysis, refactoring triage, and automated fixes

# 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                     # create engineering plan
/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, fix, verify, and open a PR for a bug

It moves through six phases: triage and reproduce the bug, gate on the verdict, plan a regression-test-first fix and create a linked engineering ticket, write the failing regression test then fix the root cause and push, verify the fix is "done done", and finally open a PR and hand off.

Triage returns one of three verdicts, posted as a [human:bug-verdict] comment on the ticket:

• 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.

Only a confirmed bug that passes the verification gate (regression test fails before the fix, passes after, and the full suite is green) gets a PR. The fix lands on an autofix/<eng-key> branch with commits referencing both the PM and engineering keys, then human pr create opens the PR (forge and repo derived from the git origin remote). A [human:ready-for-review] handoff comment is posted on the PM ticket carrying the engineering:, branch:, commits:, and pr: lines, and the TUI's (R) marker links straight to the PR.

The whole trail lives on the trackers — bug comment, engineering ticket, and PR — so no .human/ working files are produced. If the build or tests aren't green, or human pr create fails, 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: me@work.com
    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 5-stage workflow board (Backlog → Product planning → Implementation → Verification → Done): each card is a PM ticket and dragging a card forward one column triggers that stage's human action via the daemon. 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

Documentation

Overview

Human is a CLI tool that enables AI agents to interact with issue trackers and project management tools as human developers would.

It provides a unified interface across multiple issue trackers including Jira, GitHub, GitLab, Linear, Azure DevOps, and Shortcut. Additional integrations include Notion, Figma, and Amplitude.

Features

• One CLI for multiple trackers with JSON and Markdown output
• Claude Code skills for ticket analysis and implementation planning
• Definition of Ready checks for issue quality
• Notion workspace search and page reading
• Figma design browsing and component inspection
• Amplitude analytics querying

Usage

human list                    # List issues
human get TICKET-123          # Get issue details
human create --title "..."    # Create an issue
human transition TICKET-123   # Transition issue status
human statuses                # List available statuses

For full usage details, run:

human --help