ForgeHive^AI

Context-aware AI development environment — one binary, your stack.
fh init  ·  fh confirm  ·  Claude knows your codebase.

What is ForgeHiveAI?

forgehive (fh) is a CLI that permanently equips Claude Code with your codebase context — and actively checks generated code for security issues.

Claude loses all project knowledge between sessions. forgehive solves this by writing a .forgehive/ directory into your target project that Claude reads automatically at every session start.

Core capabilities:

• Stack Scanner — detects tech stack, dependencies, and project structure automatically
• Persistent Memory — context and session notes survive every restart
• Story & Epic Tracking — lightweight agile backlog inside .forgehive/memory/
• Velocity Tracking — sprint velocity history, rolling average, and capacity hints
• Party Mode — specialized agent sets, each agent in its own isolated git worktree
• MCP Wiring — preconfigured connectors for 10 services, API keys stored securely in ~/.forgehive/
• Security Suite — SAST, secret scanner, CVE check, CISO reports (GDPR/SOC2/HIPAA)
• CI Integration — CI health report and GitHub Actions template generator
• Codebase Map — file/line/import table for navigation and onboarding
• Team Sync — share memory across the team via a dedicated git branch
• AGENTS.md — cross-tool standard (Cursor, Copilot, Gemini CLI, Codex, Windsurf)

Design principle: writes exclusively to .forgehive/ in the target project. No globbing outside the project root. Never overwrites files it didn't create.

Status: v0.7.7 — Stable

297 passing tests back the commands listed below. The v0.7 feature set has been validated end-to-end.

Stable — use with confidence:

Experimental — works in tests, not yet live-validated:

If you run into issues, please open an issue on GitHub. The most valuable feedback right now is a real fh init run on your project — does Claude actually pick up the context?

Prerequisites

• Node.js ≥ 18 — check with node --version
• Claude Code installed and configured (claude CLI available)
• git — required for Party Mode worktrees, fh sync, and the guardrails hook

Documentation

Installation

From npm (recommended)

npm install -g forgehive

This makes both fh and forgehive available globally.

From source (for development)

git clone https://github.com/matharnica/forgehive
cd forgehive
npm install
npm run build      # compiles to dist/cli.js (~259 KB)
npm link           # makes 'fh' available globally

Verify the installation:

fh --version       # should print 0.7.7
fh --help          # lists all available commands

Quick Start

Step 1: Initialize your project

Navigate to any project you want Claude to understand, then run:

cd my-project
fh init

fh init does the following in order:

1. Scans your project — detects language, framework, dependencies, directory structure
2. Creates .forgehive/ with the full harness (capabilities, memory, skills, permissions)
3. Merges a context block into CLAUDE.md (creates it if it doesn't exist, never overwrites existing content)
4. Writes AGENTS.md to the project root (cross-tool agent standard)
5. Installs 16 expert skill files into .forgehive/skills/expert/

Step 2: Confirm the detected stack

fh confirm

This changes capabilities.yaml from status: draft to status: confirmed. Claude won't use the context as authoritative until it's confirmed — this gives you a chance to review what was detected before committing to it.

After confirmation, open a new Claude Code session in the project. Claude will automatically read .forgehive/ and know your stack, constraints, and memory.

Step 3: Run a security audit (recommended)

fh security scan          # finds secrets and SAST vulnerabilities
fh security deps          # checks npm dependencies for known CVEs
fh security report gdpr   # generates a CISO-ready compliance report

Commands Reference

Setup & Lifecycle

Running fh init on a project that already has .forgehive/ prints a warning and exits. Use fh init --force to re-initialize (overwrites capabilities.yaml and scans again). To update only the scan, use fh scan --update.

When to use fh rollback: If you want to remove forgehive from a project entirely. It removes exactly the block it inserted into CLAUDE.md (nothing else) and deletes .forgehive/.

Scan

The scan stores a hash of the project state. fh scan --check compares the current state against the stored hash and warns if dependencies or structure have changed significantly since the last scan.

Status & Cost Tracking

How spend limits work: Once set, fh cost checks your current spend against the configured limits every time it runs. When the alert threshold is reached, it prints a warning. When the hard limit is reached, it exits with a non-zero code — you can use this in CI or hooks to stop work automatically.

Security Suite

The security suite consists of five commands:

fh security scan

fh security scan

Runs two scanners in sequence:

1. Secret Scanner — searches all source files for exposed credentials using 8 regex patterns:

   • Anthropic API keys (sk-ant-...)
   • OpenAI API keys (sk-... non-Anthropic)
   • GitHub tokens (ghp_...)
   • AWS Access Key IDs (AKIA...)
   • Slack bot tokens (xoxb-...)
   • PEM private keys (-----BEGIN ... PRIVATE KEY)
   • Generic password assignments (password = "...")
   • Generic token assignments (token = "...")

2. SAST Scanner — static analysis for 6 vulnerability classes:

   • SQL Injection (HIGH)
   • XSS / unescaped output (HIGH)
   • eval() usage (HIGH)
   • Path traversal (../ in file operations) (MEDIUM)
   • Weak random numbers (Math.random() in security contexts) (LOW)
   • Hardcoded credentials in source (CRITICAL)

Exit codes: exits 1 if CRITICAL or HIGH findings exist — safe to use in CI pipelines.

Secrets are never stored verbatim. Findings show only the first 6 characters followed by ***.

fh security deps

fh security deps

Runs npm audit and formats the output. Shows vulnerable packages grouped by severity (critical, high, moderate, low) with CVE identifiers and fix recommendations.

fh security report

fh security report          # no compliance framework
fh security report gdpr     # GDPR-specific checks and recommendations
fh security report soc2     # SOC 2 Type II relevant controls
fh security report hipaa    # HIPAA technical safeguard checklist

Generates a Markdown CISO report at .forgehive/security-report.md. The report includes:

• Overall risk score (CLEAN / LOW / MEDIUM / HIGH / CRITICAL)
• Secret scan results
• SAST findings with file paths and line numbers
• Dependency vulnerabilities
• Compliance-mode-specific recommendations and gaps
• Timestamp and project metadata

fh security audit

fh security audit

Displays the audit trail — every fh security command execution is logged in JSONL format to .forgehive/audit.log. Shows timestamp, command, user, and outcome. Useful for compliance documentation.

fh security permissions

fh security permissions

Shows permissions.yaml — the file access control list for each agent. Each agent (Nora, Eli, Remy, Suki, Viktor, Kai, Sam, Vera) has explicit read, write, and deny lists. This prevents agents from accidentally touching files outside their scope.

CI

fh ci                          # run CI health report (text output)
fh ci --format json            # output report as JSON
fh ci --format markdown        # output report as Markdown
fh ci --fail-on critical       # exit 1 only on CRITICAL findings
fh ci --fail-on high           # exit 1 on HIGH or CRITICAL
fh ci --fail-on any            # exit 1 on any finding
fh ci --init                   # generate a GitHub Actions workflow template

fh ci aggregates security scan, dependency audit, and test results into a single CI health report. Use --init to scaffold a .github/workflows/forgehive.yml file that runs the full check on every pull request. The --fail-on flag controls which severity level causes a non-zero exit code, giving you fine-grained control over what blocks a merge.

Codebase Map

fh map

Prints a structured table of your codebase: file paths, line counts, and import relationships. Useful for onboarding a new engineer (or a new Claude session) to an unfamiliar codebase. Output goes to stdout; pipe it to a file if you want to save it.

Onboarding

fh onboard                     # generate ONBOARDING.md (stdout)
fh onboard --output ./ONBOARDING.md   # write to file

Generates a human-readable ONBOARDING.md from three sources: the detected stack in capabilities.yaml, the persistent memory in .forgehive/memory/, and the recent git log. The result is a self-contained document a new team member can read to understand the project architecture, conventions, and current state.

Changelog

fh changelog                        # full changelog from all commits
fh changelog --since v0.6.0         # changes since a specific tag
fh changelog --output CHANGELOG.md  # write to file

Parses conventional commits (feat:, fix:, chore:, docs:, etc.) and groups them into a semantic changelog. Breaking changes are surfaced separately. Requires conventional commit messages — standard for projects that use fh git-conventions.

Docs

fh docs                                        # list existing documentation
fh docs user [--output path]                   # generate user guide → docs/user-guide.md
fh docs api  [--output path]                   # generate API reference → docs/api.md
fh docs onboard [--output path]                # generate onboarding doc → ONBOARDING.md
fh docs changelog [--since tag] [--output path] # generate changelog → CHANGELOG.md
fh docs adr "<title>"                          # create Architecture Decision Record

Generates documentation from your project's stack, memory, and git history. Each subcommand writes to a default path inside docs/ (created if missing) or to the path given via --output. fh docs user and fh docs api write to docs/user-guide.md and docs/api.md respectively. fh docs adr creates a numbered ADR file in .forgehive/memory/adrs/.

fh docs onboard and fh onboard both generate onboarding documentation — they share the same generator. fh docs onboard allows specifying a custom --output path; fh onboard writes to stdout by default.

Developer Metrics

fh metrics                          # all-time developer metrics
fh metrics --since 2025-01-01       # metrics since a date

Shows commit activity broken down by author and commit type (feat, fix, chore, docs, test, refactor). Also shows rolling statistics: commit frequency, most active contributors, and type distribution. Useful for retrospectives and identifying contribution patterns.

Team Memory Sync

fh sync push                                           # push memory to default remote/branch
fh sync push --remote origin --branch forgehive-memory  # push to a specific remote branch
fh sync pull                                           # pull memory from remote
fh sync pull --remote origin --branch forgehive-memory  # pull from specific branch

fh sync shares .forgehive/memory/ across the team by pushing to (or pulling from) a dedicated git branch. This is an alternative to committing the memory directory into the main branch. On pull, existing local files are not overwritten — only new files are added, the same idempotent behavior as fh memory snapshot import.

Background Agent Execution

fh run <issue-url>                         # run agent on a GitHub/Linear issue URL
fh run <issue-url> --agent kai             # use a specific agent
fh run <issue-url> --label ready-for-ai   # filter by label

fh run launches a background agent via claude -p, passes the issue content as context, and returns immediately. The agent reads the issue, applies forgehive context from .forgehive/, and works on the task in the background. Useful for automating repetitive issues or running agents overnight. Agent output is streamed to stdout and also written to .forgehive/runs/.

Memory

Memory files live in .forgehive/memory/ and are read by Claude at session start via the CLAUDE.md block.

Memory files created by fh init:

Team snapshots: fh memory snapshot export bundles all memory files into a single JSON file you can commit or share. fh memory snapshot import imports it idempotently — existing files are never overwritten, only new files are added.

Story Cards

Story cards are lightweight user stories stored in .forgehive/memory/stories/. They integrate with /fh-sprint for velocity-based sprint planning.

fh story create "As a user I want to log in"            # create a story (auto-numbered US-N)
fh story create "As a user I want to log in" --epic EPC-1 --points 3   # with epic + points
fh story list                                            # list all backlog stories
fh story list --epic EPC-1                              # filter by epic
fh story show US-1                                       # show full story card with acceptance criteria
fh story sprint US-1                                     # mark story as in-sprint (pulled into current sprint)
fh story done US-1                                       # mark story as done
fh story done US-1 --points 5                           # mark done and record actual points

Each story card is a Markdown file at .forgehive/memory/stories/US-N.md. The card includes a title, acceptance criteria placeholder, story points, epic link, and status (backlog | in-sprint | done). Stories move through backlog → in-sprint → done. When you run /fh-sprint in a Claude Code session, Claude reads the backlog and uses velocity data to suggest a realistic sprint scope.

Epics

Epics group related stories and are stored in .forgehive/memory/epics/.

fh epic create "User Authentication"                              # create an epic (auto-numbered EPC-N)
fh epic create "User Authentication" --goal "Users can log in securely"  # with a goal statement
fh epic list                                                       # list all epics
fh epic show EPC-1                                                 # show epic with linked stories and point total

Each epic card is a Markdown file at .forgehive/memory/epics/EPC-N.md. fh epic show aggregates all stories linked to the epic and displays their status and point totals.

Velocity

fh velocity show                                              # velocity history + rolling average + recommendation
fh velocity record sprint-3 --committed 21 --delivered 18    # record sprint data

fh velocity show reads the velocity history from .forgehive/memory/velocity.md and prints:

• A table of past sprints (committed vs. delivered points)
• A rolling average (last 3 sprints)
• A capacity recommendation for the next sprint

fh velocity record appends a new entry to the velocity history. The /fh-sprint slash command reads this data automatically and uses it to calibrate the sprint scope it suggests.

Party Mode

Party Mode runs specialized agent sets in parallel, each in an isolated git worktree.

fh party                    # show current party configuration
fh party --set build        # set default party to 'build'
fh party run                # start the default party
fh party run security       # start the security party specifically
fh party status             # show active party session
fh party cleanup            # remove finished worktrees

Available party sets:

Multi-model routing — defaults.yaml supports a models: key per agent set. Override via CLI:

fh party --model-map "viktor:claude-opus-4-7,kai:claude-sonnet-4-6,sam:claude-haiku-4-5"

How isolation works: fh party run creates one git worktree per agent under .forgehive/worktrees/<agent-name>/. Each agent works in its own branch and filesystem copy. Worktrees are cleaned up with fh party cleanup or automatically when the session ends cleanly.

MCP (Model Context Protocol)

Quick wiring for common services

fh wire linear       # configure Linear MCP server in .mcp.json
fh wire slack        # configure Slack MCP server
fh wire github       # configure GitHub MCP server

Supported services for fh wire: linear, slack, github, sentry, notion, postgres, jira, pagerduty, datadog, figma

This writes the correct MCP server configuration to .mcp.json in the project root. Claude Code picks up .mcp.json automatically.

Credential management

API keys are stored encrypted at ~/.forgehive/credentials.json (chmod 600, user-only access):

fh mcp auth add github GITHUB_TOKEN=ghp_yourtoken
fh mcp auth add linear LINEAR_API_KEY=lin_api_key
fh mcp auth add slack SLACK_BOT_TOKEN=xoxb-... SLACK_TEAM_ID=T123

fh mcp auth list             # show which services have stored credentials
fh mcp auth remove github    # delete credentials for a service

Registry search and install

fh mcp search "database"              # search Smithery registry
fh mcp add @modelcontextprotocol/server-postgres
fh mcp add @smithery/some-server --env API_KEY SECRET_KEY

Trust Layer: fh mcp add checks the npm scope before installing. Trusted scopes:

• @modelcontextprotocol — official MCP servers
• @anthropic — Anthropic packages
• @smithery — Smithery registry
• @github — GitHub packages
• @microsoft — Microsoft packages

Unscoped packages or unknown scopes trigger a warning before installation proceeds.

Skills

Skills are Markdown instruction files that Claude reads when you reference them in a session.

fh skills list              # show all available skills
fh skills regen             # regenerate skills from templates (AI-assisted)
fh skills pull <git-url>    # pull expert skills from a team git repo

Pulling team skills:

fh skills pull https://github.com/my-team/ai-skills.git

Clones the repo with --depth=1, copies all .md files from the skills/expert/ subdirectory (or root if no skills/expert/ exists) into .forgehive/skills/expert/. Existing files are not overwritten.

Expert Skills installed by fh init (16 files):

Slash Commands

The following slash commands are available inside Claude Code sessions:

/fh-sprint in detail: Reads .forgehive/memory/stories/ for backlog items, .forgehive/memory/velocity.md for historical capacity, and .forgehive/memory/epics/ for epic context. Suggests a sprint scope as a list of story cards with Fibonacci point estimates. When you close the sprint, it prompts you to record delivered points so velocity history stays up to date. If Linear or GitHub MCP servers are connected, it can pull issues directly from those services.

What fh init Creates

my-project/
  .forgehive/
    capabilities.yaml          <- detected stack (status: draft -> confirmed)
    scan-result.yaml           <- raw scanner output
    .scan-hash                 <- checksum for fh scan --check
    harness/
      architecture.md          <- codebase overview for Claude
      constraints.yaml         <- max_lines, require_tests, style rules
      permissions.yaml         <- per-agent file access control (read/write/deny)
    memory/
      MEMORY.md                <- index of all memory files
      project.md               <- project context and open decisions
      feedback.md              <- corrections + confirmed approaches
      stack.md                 <- stack details the scanner can't detect
      adrs/                    <- architecture decision records
      stories/                 <- story cards (US-N.md)
      epics/                   <- epic cards (EPC-N.md)
      velocity.md              <- sprint velocity history
    skills/
      generated/               <- AI-generated skills (fh skills regen)
      expert/                  <- 16 preinstalled expert skills
      workflows/               <- MCP workflow skills
    worktrees/                 <- isolated git worktrees (fh party run)
    runs/                      <- background agent output (fh run)
    audit.log                  <- JSONL audit trail (fh security commands)
    cost-config.yaml           <- spend limits (fh cost --limit/--alert)
  AGENTS.md                    <- cross-tool agent standard
  CLAUDE.md                    <- forgehive block inserted, rest preserved

CLAUDE.md Merge Behavior

fh init never overwrites CLAUDE.md. Three cases:

The block is delimited by <!-- forgehive:start --> and <!-- forgehive:end --> markers. fh rollback removes exactly this block and nothing else.

AGENTS.md — Cross-Tool Standard

fh init generates AGENTS.md in the project root following the Linux Foundation / AAIF standard. This file is read automatically by:

• Cursor — agent behavior configuration
• GitHub Copilot — workspace instructions
• Gemini CLI — project context
• OpenAI Codex — coding guidelines
• Windsurf — agent policies

You only maintain one file; all tools benefit.

Agents

Guardrails

fh init installs a Bash hook at .claude/settings.json that blocks:

Secrets in staged git files:

• Anthropic API keys (sk-ant-...)
• GitHub tokens (ghp_...)
• AWS Access Key IDs (AKIA...)
• Slack bot tokens (xoxb-...)
• PEM private keys

Dangerous commands:

• git push --force
• git reset --hard
• rm -rf /
• DROP TABLE

The hook fires on every bash command execution in Claude Code and exits 1 if a match is found.

Typical Workflows

New project setup

cd my-project
fh init
fh confirm
# Open Claude Code -> Claude now has full context

After adding new dependencies

npm install new-package
fh scan --update    # re-scan to pick up new dependency
fh confirm          # re-confirm the updated capabilities

Weekly security check

fh security scan            # check for secrets and SAST issues
fh security deps            # check for new CVEs in dependencies
fh security report gdpr     # update compliance report

CI integration

fh ci --init                  # scaffold .github/workflows/forgehive.yml
fh ci --format markdown --fail-on high   # use in existing CI scripts

Generating onboarding documentation

fh map                        # review codebase structure
fh onboard --output ONBOARDING.md   # generate onboarding document
git add ONBOARDING.md
git commit -m "docs: add forgehive-generated onboarding"

Generating a changelog

fh changelog --since v0.6.0 --output CHANGELOG.md

Sprint planning

# Set up your backlog
fh epic create "User Authentication" --goal "Users can log in securely"
fh story create "As a user I want to log in" --epic EPC-1 --points 3
fh story create "As a user I want to reset my password" --epic EPC-1 --points 2

# Check current velocity
fh velocity show

# Open Claude Code and run:
# /fh-sprint
# Claude reads velocity + backlog and suggests scope

# At end of sprint
fh velocity record sprint-1 --committed 13 --delivered 11
fh story done US-1
fh story done US-2

Sharing context with the team

fh memory snapshot export ./team-context.json
git add team-context.json
git commit -m "chore: update shared forgehive context"

# On another machine:
fh memory snapshot import ./team-context.json

# Or use the sync approach (no committed file):
fh sync push --remote origin --branch forgehive-memory
# teammate runs:
fh sync pull --remote origin --branch forgehive-memory

Starting a multi-agent build session

fh party --set build
fh party run
# -> Creates worktrees for Viktor (architect), Kai (engineer), Sam (QA)
# -> Each Claude Code session opens in its own isolated worktree

fh party status     # check what's running
fh party cleanup    # clean up after the session

Connecting Linear and GitHub

fh wire linear
fh mcp auth add linear LINEAR_API_KEY=lin_api_...

fh wire github
fh mcp auth add github GITHUB_TOKEN=ghp_...

# Credentials stored at ~/.forgehive/credentials.json (chmod 600)
fh mcp auth list    # verify both services are stored

Running a background agent on an issue

fh run https://github.com/my-org/my-repo/issues/42 --agent kai
# Kai reads the issue, applies forgehive context, works in background
# Output streamed to stdout and saved to .forgehive/runs/

Configuration Files

.forgehive/capabilities.yaml

Auto-generated by fh init, confirmed by fh confirm. Contains:

• status: draft | confirmed
• Detected language, framework, package manager
• Key directories and entry points
• Test configuration

Edit this file manually to correct anything the scanner got wrong, then run fh confirm again.

.forgehive/harness/constraints.yaml

Defines Claude's behavior rules for this project:

• max_lines_per_file: soft limit for file size
• require_tests: whether to require tests for new code
• test_framework: which test runner to use
• Style and formatting preferences

.forgehive/harness/permissions.yaml

Per-agent file access control. Default permissions are conservative — agents can only read/write files relevant to their role. Edit to expand or restrict access.

~/.forgehive/credentials.json

Global credential store (chmod 600). Managed exclusively via fh mcp auth commands — do not edit manually.

Tech Stack

npm run build       # esbuild -> dist/cli.js
npm run typecheck   # tsc --noEmit
npm test            # node --import tsx/esm --test test/*.test.ts

Changelog

License

Elastic License 2.0 (ELv2) — kostenlos selbst hosten für den eigenen Betrieb. Weiterverkauf als Managed Service nicht erlaubt.