thrunt-god

---

Installation

npx thrunt-god@latest --claude --local

Bootstrap the hunt command surface into your local IDE environment.

IDE	Command
Claude Code / Gemini	/hunt:help
OpenCode	/hunt-help
Codex	$hunt-help
Copilot	/hunt-help
Cursor / Windsurf	hunt-help

Install the VS Code extension alpha

Download thrunt-god-0.3.0.vsix from the v0.3.0 release.

Then install it one of two ways:

1. In VS Code, open Extensions, click the ... menu, choose Install from VSIX..., and select the downloaded file.
2. From terminal:

code --install-extension thrunt-god-0.3.0.vsix

After install, open a folder containing .planning/MISSION.md or .hunt/MISSION.md and the THRUNT sidebar will activate automatically.

---

The Five Phases

Every hunt resolves through five phases. Each step is explicit.

Phase
Signal	A detection, anomaly, lead, or intel input opens the case
Hunt	Hypotheses are formed, scoped, and made testable
Swarm	Parallel agents execute structured investigations across available sources
Receipt	Every claim is bound to exact queries, timestamps, and evidence lineage
Publish	Only validated findings are packaged for downstream consumers

---

Hunt Commands

Command	Purpose
/hunt:new-program	Stand up a long-lived hunt program
/hunt:new-case	Open a case from a signal
/hunt:map-environment	Inventory data sources, access, and topology
/hunt:shape-hypothesis	Develop and refine testable hypotheses
/hunt:plan <phase>	Plan a hunt phase
/hunt:run <phase>	Execute a hunt phase
/hunt:validate-findings [phase]	Validate evidence chain for findings
/hunt:publish [target]	Package and ship findings
/hunt:help	Show all commands and usage

Thrunt Commands

Utility and orchestration commands (/thrunt:*) for workspace management, diagnostics, settings, and agent control.

---

Common Flows

Single signal

/hunt:new-case
/hunt:shape-hypothesis
/hunt:plan 1
/hunt:run 1
/hunt:validate-findings 1
/hunt:publish

Long-lived program

/hunt:new-program
/hunt:map-environment
/hunt:new-case
  ... repeat per signal ...

Pack-seeded signal

/hunt:new-case --pack domain.identity-abuse
/hunt:run 1
/hunt:validate-findings 1

Autonomous

/thrunt:autonomous

Runs all remaining phases end-to-end: discuss, plan, execute. Pauses only for operator decisions.

---

Artifacts

All hunt state lives in a planning directory at the project root (.planning/ by default). Every query, receipt, and finding is a file, not a summary.

.planning/
├── config.json             # Project settings (mode, profile, connectors, workflow toggles)
├── MISSION.md              # Hunt program mission and scope
├── HYPOTHESES.md           # Testable hypotheses with status tracking
├── SUCCESS_CRITERIA.md     # Definition of done for the program
├── HUNTMAP.md              # Phase breakdown and execution roadmap
├── STATE.md                # Current phase, progress, blockers
├── FINDINGS.md             # Validated findings only
├── EVIDENCE_REVIEW.md      # Evidence chain audit
├── QUERIES/                # Exact queries run, with timestamps
├── RECEIPTS/               # Execution receipts per phase task
├── DETECTIONS/             # Detection rules promoted from findings
├── environment/
│   └── ENVIRONMENT.md      # Data source inventory and access map
├── phases/                 # Per-phase plans, research, and results
├── workstreams/            # Parallel hunt cases (optional)
├── milestones/             # Archived completed milestones
└── published/              # Final deliverables

Configuration

Settings live in .planning/config.json, created by /hunt:new-program and editable via /thrunt:settings. Global defaults in ~/.thrunt/defaults.json are merged into every new project config.

Setting	Default	What it controls
mode	interactive	interactive confirms at each step, yolo auto-approves
granularity	standard	Phase count: coarse (3-5), standard (5-8), fine (8-12)
model_profile	balanced	Model tier per agent: quality, balanced, budget, inherit
planning.commit_docs	true	Whether .planning/ is committed to git
git.branching_strategy	none	none, phase (branch per phase), milestone (branch per version)

Full schema and connector profiles: docs/CONFIGURATION.md

Custom planning directory

Set THRUNT_PLANNING_DIR to change the directory name. This affects all path resolution, project root detection, and artifact storage.

export THRUNT_PLANNING_DIR=".hunt"

Storage

By default, .planning/ is committed to git so hunt artifacts travel with the repo. To keep artifacts local:

1. Add .planning/ to .gitignore
2. Set planning.commit_docs: false and planning.search_gitignored: true in config
3. If previously tracked: git rm -r --cached .planning/

Workstreams (/thrunt:new-workspace) create isolated artifact trees under .planning/workstreams/{name}/ for parallel hunts in the same project.

Bootstrap fills confirmed fields immediately. TBD only marks live environment or operator-supplied facts that are still unknown.