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
• 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)
• 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: Early Alpha (v0.6)

This is an early release. The codebase is clean — TypeScript, 217 passing tests, single bundle — but several features have not yet been tested against a real project.

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 and the guardrails hook

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 (~205 KB)
npm link           # makes 'fh' available globally

Verify the installation:

fh --version       # should print 0.6.0
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

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.

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.

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:

Model mapping — assign specific Claude models per agent:

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

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
    skills/
      generated/               ← AI-generated skills (fh skills regen)
      expert/                  ← 16 preinstalled expert skills
      workflows/               ← MCP workflow skills
    worktrees/                 ← isolated git worktrees (fh party 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

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

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

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

License

MIT