Why Nemesis?

When you orchestrate a team of AI agents (Claude Code, Copilot, etc.), you need structure: who does what, what's been assigned, what's been delivered, what's broken. Nemesis gives you a file-first CLI cockpit to manage all of that without a server, a database, or any runtime dependency. JSON files in your repo are the single source of truth. A remote HCM (Human Capital Management) graph keeps everything in sync.

Quick Start

# Install globally
npm install -g @arka-labs/nemesis

# Initialize a project in your repo
nemesis init

# Add an AI agent to your team
nemesis team add

# Check project status
nemesis status

Requires Node.js >= 20. Single runtime dependency (xstate for workflow state machine).

Interactive Mode

Run nemesis without arguments to launch the interactive menu:

   █████╗ ██████╗ ██╗  ██╗ █████╗ ██╗      █████╗ ██████╗ ███████╗
  ...

  ARKA Labs CLI v1.2.0  nemesis

  ── Projet ──────────────────────────
  ❯ status      — Etat du projet + alertes
    init        — Scaffold structure projet
    doctor      — Diagnostic complet

  ── Equipe ──────────────────────────
    team:list   — Organigramme hierarchique
    team:panneau— Panneau agent
    team:add    — Ajouter un agent
    kars        — Profils Kairos disponibles

  ── Travail ─────────────────────────
    orch        — Dashboard orchestration
    inbox       — Documents → Mission Contract
    mission     — Mission Contracts
    odm         — Ordres de Mission
    audit       — Audits techniques

  ── Memoire ─────────────────────────
    notes       — Notes et CRs agents
    notewriter  — Gestion contexte agent

  ── Infra ───────────────────────────
    services    — Connexions LLM
    hcm         — Synchronisation HCM
    auth        — Login HCM
    kairos      — Hooks & contexte agent

  Fleches ↑↓ pour naviguer, Enter pour selectionner, q pour quitter

Navigate with arrow keys (or j/k), press Enter to select, q or Escape to quit.

Commands

nemesis init

Scaffold a new project structure in the current repository.

nemesis init
nemesis init --bare --id MY-PROJECT --name "My Project" --desc "Description"

Creates:

• .nemesis/HCM/ — 10 subdirectories for project artifacts (contracts, odm, cr, decisions, etc.)
• .nemesis/template/ — 8 JSON templates for structured documents
• CONTEXT_PROJECT_*.json — project context file
• REGISTRY-*.json — team registry (PM only at start)
• PROCESS.md — workflow documentation

nemesis team

The core command. Manages your AI agent team.

nemesis team add

Onboard a new agent through an interactive 9-step process:

1. Detect project
2. Select Kairos profile from HCM (or manual entry)
3. Configure agent (name, role, hierarchy)
4. Create memory.md for the agent
5. Create contributor card in .nemesis/HCM/contributors/
6. Update team registry
7. Update ~/.claude/CLAUDE.md (agent table + workflow tree)
8. Generate onboarding prompt
9. Return launch command

# Interactive (recommended)
nemesis team add

# Non-interactive
nemesis team add --name Agent_Dev --role Implementeur --reports-to PM --no-prompt

Output:

  ✓ Projet detecte           → MY-PROJECT
  ✓ Agent configure           → Agent_Dev — Implementeur
  ✓ memory.md cree            → .nemesis/claude/Agent_Dev/memory.md
  ✓ Contributor card creee    → .nemesis/HCM/contributors/CONTRIB-Dev.json
  ✓ Registre mis a jour       → Lane ajoutee : Agent_Dev
  ✓ CLAUDE.md mis a jour      → Tableau + Workflow
  ✓ Prompt d'onboarding genere → .nemesis/onboarding/prompt-Dev.md
  ✓ Commande de lancement      → claude --prompt .nemesis/onboarding/prompt-Dev.md

  Pour demarrer l'agent :
    claude --prompt .nemesis/onboarding/prompt-Dev.md

nemesis team list

Display the organizational tree.

nemesis team list

  Jeremy Grimonpont (PM)
  ├── Agent_Nemesis-CLI (Architecte / QA)
  │   └── Agent_Bot-CLI (Implementeur)
  └── Agent_ARCH-CLI (Archiviste documentaire)

nemesis team inspect [agent]

Detailed view of a specific agent: memory stats, assigned OdMs, recent CRs.

nemesis team inspect Agent_Bot-CLI
nemesis team inspect Agent_Bot-CLI --format json

  Agent     : Agent_Bot-CLI
  Kind      : agent
  Role      : Implementeur
  Reporte a : Agent_Nemesis-CLI
  MCP       : (aucun)
  Memory    : .nemesis/claude/Agent_Bot-CLI/memory.md (2.1 KB, maj 2026-03-10)

  OdMs assignes :
  ┌──────────────────┬──────────┬─────────────────────────────┐
  │ OdM              │ Status   │ Titre                       │
  ├──────────────────┼──────────┼─────────────────────────────┤
  │ ODM-NEMESIS-004  │ VALIDE   │ Infrastructure + Team       │
  └──────────────────┴──────────┴─────────────────────────────┘

nemesis team remove [agent]

Archive an agent. Files are preserved for traceability (memory.md renamed to .archived).

nemesis team remove Agent_Dev

nemesis project

nemesis project status    # Synthetic project view: team size, OdMs, decisions, CRs
nemesis project init      # Alias for "nemesis init"

nemesis mission

Manage Mission Contracts (high-level work packages with gates and task registries).

nemesis mission init              # Create a new Mission Contract (auto-generates ID)
nemesis mission init MCT-001      # Create with explicit ID
nemesis mission list              # List all contracts
nemesis mission inspect MCT-001   # Full contract content: cadrage, workflow, tasks

nemesis odm

Manage Ordres de Mission (specific, assignable work items derived from Mission Contracts).

nemesis odm init              # Create a new OdM (auto-generates ID)
nemesis odm init ODM-004      # Create with explicit ID
nemesis odm list              # List all OdMs with status/assignee/priority
nemesis odm inspect ODM-004   # Full OdM content + associated CRs

nemesis status

Quick project status with smart alerts.

nemesis status

  MY-PROJECT — 2 agent(s), 3 OdM, 1 en cours

  ⚠ Equipe vide — ajoutez un agent : nemesis team add
  ⚠ ODM-003 en DRAFT mais non assigne
  ⚠ Agent_Bot n'a pas mis a jour sa memoire depuis 4 jours

Alerts include: empty team, missing Mission Contracts, OdMs without CRs, stale agent memory, unassigned drafts.

nemesis hcm

Synchronize local JSON files with the remote HCM knowledge graph.

nemesis hcm status    # Connection diagnostic (ping, auth, graph stats)
nemesis hcm sync      # Scan .nemesis/HCM/, diff hashes, push modified files
nemesis hcm search "query"  # Full-text search in HCM documents

The sync engine:

1. Scans .nemesis/HCM/ recursively for JSON files
2. Computes SHA-256 hashes and compares with last sync state
3. Pushes only modified files to the HCM API
4. Ignores template_* and legacy_* files

nemesis doctor

Full system diagnostic.

nemesis doctor

  Structure .nemesis/HCM/ :
    ✓ contracts/
    ✓ odm/
    ✓ cr/
    ...

  Templates .nemesis/template/ :
    ✓ 8 templates presents

  Config :
    ✓ Projet detecte : MY-PROJECT

  HCM :
    ✓ Connexion : 142ms
    ✓ Auth : API key valide
    ✓ Graphe : 847 noeuds, 1203 edges

  Registre :
    ✓ REGISTRY (3 membres)
    ✓ CLAUDE.md sync (2 agents)

  Agents :
    ✓ Agent_Nemesis-CLI : memory.md present (3.2 KB)
    ✓ Agent_Bot-CLI : memory.md present (1.8 KB)

  Tout est OK.

Checks: directory structure (10 dirs), templates (8 files), config file, HCM connection (ping, auth, graph), registry vs CLAUDE.md sync, agent memory files.

nemesis orch

Orchestration dashboard — monitor dispatches, escalations, and deliveries in real-time.

nemesis orch              # Auto-refresh every 2s, quit with 'q'
nemesis orch --once       # Display once and exit
nemesis orch --format json

The daemon polls for OdMs with status READY_TO_DISPATCH, auto-dispatches via headless agents, and routes results through the configured routing chain.

nemesis services

Manage LLM provider connections and hook lifecycle.

# Connexions
nemesis services connexions add       # Add provider (Anthropic, OpenAI, Gemini, Ollama, etc.)
nemesis services connexions list      # List all connections with status
nemesis services connexions test      # Health check (auth/endpoint)
nemesis services connexions live      # Full validation (real LLM call + file I/O)

# Service assignment
nemesis services config               # Assign connections to services (notes, odm, mc)
nemesis services status               # Overview of all assignments + fallback chains

# Hooks
nemesis services hooks status         # Hook state (active/inactive count)
nemesis services hooks setup          # Enable all hooks
nemesis services hooks reset          # Disable all hooks

nemesis notes

Browse agent notes and CRs with filtering and timeline views.

nemesis notes                         # Interactive menu
nemesis notes agent Agent_Dev         # View by agent
nemesis notes timeline                # Project timeline (all agents)
nemesis notes inspect NOTE-Dev-042    # Display note or CR by ID
nemesis notes agent Agent_Dev --cr    # Filter CRs only
nemesis notes agent Agent_Dev --level L3  # Filter by level

nemesis notewriter

Manage agent context: notes, CRs, and session replay.

nemesis notewriter status Agent_Dev   # NoteWriter state
nemesis notewriter cr Agent_Dev       # Generate manual CR (calls LLM)
nemesis notewriter list Agent_Dev     # List notes and CRs
nemesis notewriter inspect Agent_Dev NOTE-Dev-042
nemesis notewriter replay Agent_Dev   # Replay session from JSONL log

nemesis kairos

Install and manage Claude Code hooks for agent context injection.

nemesis kairos hooks setup            # Install 4 hooks into .claude/settings.json
nemesis kairos hooks status           # Verify hook installation
nemesis kairos hooks remove           # Uninstall hooks
nemesis kairos push --to Agent_Dev --type CR_DEPOSITED  # Send event
nemesis kairos events                 # List pending events
nemesis kairos clear --agent Agent_Dev  # Purge event queue

Four hooks are installed: SessionStart (context injection), UserPromptSubmit (situation detection + turn logging), Stop (note generation + CR check), PreCompact (context re-injection).

nemesis auth

Configure HCM authentication.

nemesis auth login    # Configure URL + API key (test → save → sync shell RC)
nemesis auth status   # Show active connection + live ping
nemesis auth logout   # Remove credentials

nemesis kars

Browse available Kairos profiles by sector.

nemesis kars                   # Interactive sector picker
nemesis kars search --sector cybersecurity
nemesis kars search --format json

nemesis audit

Run template-based technical audits.

nemesis audit list             # Available audit templates
nemesis audit run              # Launch an audit (template → target → prompt generation)
nemesis audit reports          # View generated reports

nemesis inbox

Human document pipeline: intake → Leader dispatch → Mission Contract draft.

nemesis inbox list             # Pending documents
nemesis inbox add spec.pdf     # Add document to inbox
nemesis inbox process          # Dispatch to Leader for MC drafting
nemesis inbox history          # Completed documents

nemesis run

Resume an agent session.

nemesis run agent:Agent_Dev                  # Interactive session (claude --resume)
nemesis run agent:Agent_Dev --p "fix the bug"  # Direct prompt (headless)

Global Flags

| Flag | Description | |------|-------------| | --format json\|text\|yaml | Output format (default: text) | | --no-color | Disable ANSI colors | | --verbose | Detailed error output | | -h, --help | Help (global and per-command) | | -V, --version | Print version |

Architecture

nemesis-cli/
├── src/
│   ├── index.js              # Entry point (#!/usr/bin/env node)
│   ├── cli.js                # Command dispatcher + interactive menu (18 commands)
│   ├── config.js             # Config loader + project auto-detection
│   └── commands/             # One handler per command
│       ├── init.js           # nemesis init
│       ├── team.js           # nemesis team (add/list/inspect/remove)
│       ├── project.js        # nemesis project (status/init)
│       ├── mission.js        # nemesis mission (init/list/inspect)
│       ├── odm.js            # nemesis odm (init/list/inspect)
│       ├── status.js         # nemesis status
│       ├── hcm.js            # nemesis hcm (sync/status/search)
│       ├── doctor.js         # nemesis doctor
│       ├── orch.js           # nemesis orch (orchestration dashboard)
│       ├── services.js       # nemesis services (LLM connections + hooks)
│       ├── notes.js          # nemesis notes (browse notes/CRs)
│       ├── notewriter.js     # nemesis notewriter (agent memory management)
│       ├── kairos.js         # nemesis kairos (hooks + event bus)
│       ├── auth.js           # nemesis auth (HCM credentials)
│       ├── kars.js           # nemesis kars (profile search)
│       ├── audit.js          # nemesis audit (technical audits)
│       ├── inbox.js          # nemesis inbox (document pipeline)
│       ├── run.js            # nemesis run (resume agent session)
│       └── _helpers.js       # Shared utilities (ensureProject, pickFromList)
├── lib/
│   ├── core/                 # Business logic (pure functions, no UI)
│   │   ├── project.js        # initProject, detectProject, getProjectStatus
│   │   ├── team.js           # teamAdd, teamList, teamInspect, teamRemove
│   │   ├── registry.js       # Registry CRUD (addLane, removeLane, getLanes)
│   │   ├── odm.js            # initOdm, listOdm, inspectOdm, setOdmStatus
│   │   ├── mission.js        # initMission, listMissions, inspectMission
│   │   ├── templates.js      # Template loading (priority: .nemesis > .owner > embedded)
│   │   ├── generators.js     # Generate memory.md, onboarding prompts, CLAUDE.md updates
│   │   ├── logger.js         # Minimal stderr logger (warn, error, debug)
│   │   ├── secrets.js        # AES-256-GCM encryption with PBKDF2 key derivation
│   │   ├── audit.js          # Audit template management + prompt generation
│   │   ├── inbox.js          # Document pipeline (pending → processing → done)
│   │   ├── connexions.js     # LLM provider connection registry
│   │   ├── services.js       # Service configuration (assignments, fallback chains)
│   │   ├── agent-launcher.js # Spawn Claude CLI with streaming JSON parsing
│   │   ├── profile-picker.js # Kairos profile selection from HCM
│   │   ├── notewriter/       # Agent memory system
│   │   │   ├── config.js     # NoteWriter configuration (enable, timers, levels)
│   │   │   ├── log.js        # Session turn logging (JSONL, open/close)
│   │   │   ├── notes.js      # Note generation via LLM (L1-L5 depth)
│   │   │   ├── cr.js         # CR generation (combine notes, LLM summary)
│   │   │   ├── reader.js     # Timeline + filtering across notes/CRs
│   │   │   ├── paths.js      # Path resolution (month-bucketed directories)
│   │   │   └── registry.js   # Notes/CRs index with sequential IDs
│   │   └── flowmap/          # Workflow state machine (XState v5)
│   │       ├── machine.js    # 18-state workflow (F00→FIN)
│   │       ├── api.js        # Actor management + event dispatch
│   │       ├── persistence.js # XState snapshot I/O
│   │       └── cli-helpers.js # Display helpers for flowmap status
│   ├── kairos/               # Agent orchestration hooks
│   │   ├── hook-handlers.js  # 4 hook entry points (pre/dynamic/post/compact)
│   │   ├── hook-installer.js # Claude Code hooks installation
│   │   ├── context-injector.js # Unified context injection via stdout
│   │   ├── context-writer.js # Situation persistence
│   │   ├── context-loader.js # Agent context resolution
│   │   ├── situation-detector.js # Keyword-based situation detection
│   │   ├── agent-runner.js   # Headless agent dispatch + result polling
│   │   ├── dispatcher.js     # LLM response classification (LEADER/HUMAN/NOISE)
│   │   ├── dispatcher-router.js # File-based routing for dispatch results
│   │   ├── event-bus.js      # Async event queue (TTL, priority, per-agent)
│   │   ├── event-router.js   # Event routing to agents
│   │   ├── flowmap-bridge.js # Signal detection → flowmap events
│   │   ├── pid-checker.js    # Agent PID registration + liveness
│   │   ├── leader-rules.js   # Leader-specific dispatch/validation rules
│   │   ├── hook-prompts.js   # Prompt templates for hooks
│   │   └── claude-invoker.js # Claude CLI invocation wrapper
│   ├── sync/                 # HCM + LLM communication
│   │   ├── hcm-client.js     # HCM HTTP client (vanilla fetch, Node 20+)
│   │   ├── sync-engine.js    # Hash-based scan/diff/sync engine
│   │   ├── health.js         # HCM connection diagnostic
│   │   ├── nemesis-client.js # Nemesis API client
│   │   ├── llm-client.js     # Multi-provider LLM client
│   │   ├── service-session.js # LLM API caller with fallback
│   │   └── fallback-engine.js # Silent cascade across connections
│   └── ui/                   # Terminal display
│       ├── brand.js          # ARKA LABS ASCII logo + branded headers
│       ├── colors.js         # ANSI color system (NO_COLOR / FORCE_COLOR aware)
│       ├── box.js            # Unicode box drawing (emoji-aware width)
│       ├── table.js          # ASCII table renderer
│       ├── tree.js           # Hierarchical tree renderer
│       ├── menu.js           # Interactive keyboard menu (arrows, j/k, scrolling)
│       ├── prompt.js         # Interactive prompts (text, choice, confirm)
│       ├── spinner.js        # Braille-pattern loading spinner
│       ├── format.js         # Output formatter (JSON / YAML / text)
│       ├── dashboard.js      # Orchestration dashboard (real-time monitoring)
│       ├── streambox.js      # Streaming JSON output renderer
│       ├── note-card.js      # Note/CR card components
│       ├── note-colors.js    # Level-based color system (L1-L5)
│       ├── note-detail.js    # Note/CR detail views
│       ├── note-filters.js   # Filter panel UI
│       ├── note-views.js     # Agent/timeline views
│       └── error-hints.js    # User-friendly error suggestions
├── templates/                # 9 embedded JSON templates
└── test/                     # 862 tests across 88 files
    ├── unit/                 # Pure function tests (68 files)
    ├── integration/          # Multi-module tests with temp directories (12 files)
    └── e2e/                  # Full workflow test

How It Fits Together

                          ┌──────────────────┐
                          │    HCM Graph      │
                          │  (remote API)     │
                          └────────▲──────────┘
                                   │ sync (hash-based)
┌──────────────┐          ┌────────┴──────────┐
│  PM (human)  │◄────────►│   nemesis CLI     │
│  via terminal│          │                   │
└──────────────┘          │  reads/writes     │
                          │  .nemesis/HCM/    │
                          └────────▲──────────┘
                                   │ JSON files
                          ┌────────┴──────────┐
                          │  AI Agents        │
                          │  (Claude Code)    │
                          │                   │
                          │  write OdM, CR,   │
                          │  decisions, etc.  │
                          └───────────────────┘

Data flow: Agents produce structured JSON artifacts (OdMs, CRs, decisions) in .nemesis/HCM/. Kairos hooks inject context at session start, detect situations dynamically, generate notes/CRs on each turn, and route dispatch results through the configured routing chain. The orchestrator daemon (nemesis orch) auto-dispatches OdMs and monitors the entire lifecycle. The PM uses Nemesis CLI to observe progress, manage the team, and orchestrate work.

Design Principles

1. File-first — All data lives in .nemesis/HCM/ as JSON files. No local database.
2. Read-heavy, write-light — The CLI reads a lot (status, inspect, list) and writes little (init, team add). Agents do the writing.
3. Daemon-light — nemesis orch provides real-time orchestration via filesystem polling (no background service required).
4. Minimal dependencies — Only xstate (workflow state machine) at runtime. All UI, crypto, and I/O use Node.js built-ins.
5. Portable — Works on any repo. Auto-detects project from .nemesis/HCM/project/CONTEXT_PROJECT_*.json.

Configuration

Config File

Optional global configuration at ~/.nemesis/config.json:

{
  "defaults": {
    "hcm_url": "https://your-hcm-server.example.com",
    "hcm_api_key_env": "HCM_API_KEY"
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | HCM_URL | HCM API base URL | (none — set via nemesis auth login) | | HCM_API_KEY | API key for HCM authentication | (none) | | NO_COLOR | Disable all ANSI colors (no-color.org) | — | | FORCE_COLOR | Force colors even without TTY | — | | NEMESIS_COLOR | Override color detection (0 = off, 1 = on) | — | | NEMESIS_VERBOSE | Enable debug logging to stderr (1 = on) | — |

Project Auto-Detection

The CLI auto-detects the current project by looking for:

1. .nemesis/HCM/project/CONTEXT_PROJECT_*.json (primary)
2. .owner/HCM/project/CONTEXT_PROJECT_*.json (legacy fallback)

No project detected? Run nemesis init or the CLI will offer to initialize one interactively.

Template Priority

When loading templates for new documents (OdM, CR, Mission Contract, etc.):

1. .nemesis/template/ (project-specific overrides)
2. .owner/template/ (legacy path)
3. templates/ (embedded defaults shipped with the package)

Embedded Templates

Nemesis ships with 9 JSON templates for structured documents:

| Template | Purpose | |----------|---------| | template_ODM-NAME-000.json | Ordre de Mission | | template_CR-ODM-NAME-000.exemple.json | Compte-Rendu (delivery report) | | template_MISSION_CONTRACT.json | Mission Contract (work package) | | template_REGISTRY-PROJECT.json | Team registry | | template_DEC-NAME-000.json | Decision record | | template_INTV-NAME-000.json | Intervention log | | template_CONTRIB-NAME.json | Contributor card | | template_TXN-NAME-000.json | Transaction record | | project-context.json | Project context |

Development

# Clone the repository
git clone https://github.com/arka-squad/arkalabs-nemesis-cli.git
cd arkalabs-nemesis-cli

# Install dependencies
npm install

# Link for local development
npm link

# Run tests
npm test              # 862 tests across 88 files
npm run test:watch    # Watch mode
npm run test:coverage # With coverage report (v8, thresholds: 50% lines / 60% functions)
npm run lint          # ESLint check
npm run lint:fix      # ESLint auto-fix

Test Structure

862 tests across 88 files, organized in three categories:

• Unit (test/unit/, 68 files) — pure function tests covering core logic, UI components, kairos hooks, notewriter, flowmap, dispatcher, event bus, secrets, logger, and more
• Integration (test/integration/, 12 files) — multi-module tests with temp directories (init, team, mission, odm, doctor, hcm-sync, services, event-bus, orch-dashboard, nemesis-mcp)
• E2E (test/e2e/, 1 file) — full workflow: init → team → mission → odm → sync → remove

Contributing

See CONTRIBUTING.md for guidelines on how to contribute.

License

Apache License 2.0 — ARKA LABS