@nfinitmonkeys/clan

Universal clan runtime for the Jungle — set up an AI agent (an Alpha) for any project, on any machine, with a persistent brain by default.

⚠️ Always use the scoped name @nfinitmonkeys/clan. The bare jungle-clan is unpublished on npm and squattable. And never npm install -g — a stale global silently shadows npx.

Quick Start — up is the door

npx -y @nfinitmonkeys/clan up

One command, one flow: a short interview (what is this clan for? what should the Alpha be called?) → the engine plans exactly what it will write → you approve → it applies (backed up, journaled, undoable) → doctor verifies.

Inside Claude Code the same door is conversational: type /clan:up.

Re-running up on an existing clan is a repair, not an error — it brings an old clan to the current standard and writes nothing if you're already there.

Scripted / automation paths

# Non-interactive standalone (no prompts):
npx -y @nfinitmonkeys/clan up --yes --alpha Relay --name my-project

# Attach to a pre-provisioned clan (credentials via env, never argv):
ALPHA_ID=<uuid> JUNGLE_API_KEY=<key> npx -y @nfinitmonkeys/clan up --yes --attach

# The classic one-shot doors still work and run the same engine:
npx -y @nfinitmonkeys/clan attach --alpha-id <uuid> --api-key <key>   # join a Jungle
npx -y @nfinitmonkeys/clan wild --yes --alpha Relay                   # standalone, no Jungle

What setup writes

All setup paths drive @nfinitmonkeys/clan-engine — a single deterministic, non-destructive authority (dry-run plans, uniform backups, journaled undo):

• .jungle/config.yaml — identity + credentials (gitignored)
• CLAUDE.md — geo-tier declaration (your existing prose is untouched)
• .claude/skills/clan-awareness/SKILL.md — the awareness skill
• .claude/commands/clan/*.md — the /clan:* slash commands (incl. /clan:up)
• .mcp.json — a jungle-local MCP server merged alongside any servers you already have (connected mode; gitignored — it holds a live key)
• .claude/settings.json — a SessionStart hook that hydrates the brain
• .brain/ — the versioned memory vault
• .clan/inventory.json — your existing agents/skills/commands, so the Alpha works with them instead of duplicating

The brain

# Seed the brain from what the project already knows (dry-run by default):
npx -y @nfinitmonkeys/clan brain build --write

# Add Claude Code session memory as a source:
npx -y @nfinitmonkeys/clan brain build --write --memory

# Have this clan's configured LLM rewrite the mined pages into real
# identity/hot/index/concept prose (grounded, re-scanned, graceful fallback
# to mechanical pages if the LLM is unavailable or misbehaves):
npx -y @nfinitmonkeys/clan brain build --write --curate

# Ask the brain a question — works on ANY configured provider:
npx -y @nfinitmonkeys/clan brain query "what is this project's deploy story?"

brain build mines README, docs/, CLAUDE.md, manifests, and code. Every source — and every curated page — is scanned for secrets/infra-ids/PHI first; anything sensitive is held back and reported, never written. Create-only: your accumulated pages are never touched.

brain query runs on cortex, openai, anthropic, or ollama — whatever set-llm configured. No vendor wall.

LLM configuration

npx -y @nfinitmonkeys/clan set-llm --provider cortex --key sk-cortex-...
# or: --provider ollama | openai | anthropic  (plus --base-url / --model)

Config lives in .jungle/config.yaml (gitignored) with an llm: block:

llm:
  provider: cortex        # ollama / openai / anthropic / cortex
  baseUrl: https://...
  apiKey: sk-...
  model: ...

Day-to-day commands

| Command | Description | |---------|-------------| | up [flags] | The ONE door — interview → plan → approval → apply → doctor | | attach / wild | Scripted setup paths (join a Jungle / standalone) | | set-llm | Configure the LLM (provider / key / base-url / model) | | brain build [--curate] | Seed the brain from existing files | | brain query "<q>" | Ask the brain (any configured provider) | | brain init / brain lint | Scaffold / health-check the vault | | start / stop | Run the Alpha (polling loop) | | serve | Local browser UI — chat with your clan in a tab | | status [--json] | Clan status (live from the Jungle when connected) | | talk "msg" | Talk to your Alpha | | inbox / thread <id> | Read messages | | policies | View governance policies | | health | Probe + report health to the Jungle (connected mode) |

Verify / repair / undo

npx -y @nfinitmonkeys/clan-engine doctor   # validate config, mcp name, brain, hook, creds
npx -y @nfinitmonkeys/clan-engine plan     # see exactly what a re-run would change
npx -y @nfinitmonkeys/clan-engine undo     # reverse the last apply

License

MIT