🔮 PhantomindAI

Universal AI Development Enhancement Layer

"You already pay for Copilot, Cursor, or Claude. PhantomindAI makes what you already have 10x more effective."

What is PhantomindAI?

PhantomindAI solves the context amnesia problem: AI assistants forget everything about your project every session, every context switch, and every time a new team member onboards.

PhantomindAI provides:

• Persistent context layer — one source of truth (SKILLS.md, RULES.md, schema.json) synced to every AI assistant automatically
• Universal LLM abstraction — one API for Anthropic, OpenAI, Gemini, Groq, Mistral, Ollama, DeepSeek, and OpenRouter, with automatic fallback and budget routing
• Agentic task execution — multi-role agent orchestration with human-in-the-loop checkpoints
• AI output quality enforcement — secret scanning, hallucination detection, dual-model verification, consistency checking
• MCP Server — expose project intelligence as a Model Context Protocol server for Cursor, Continue, Claude Code, and more
• Full observability — cost tracking, audit trails, and analytics dashboard

Table of Contents

• Installation
• Quick Start
• CLI Reference
• Configuration
• Supported AI Assistants
• Supported LLM Providers
• Programmatic API
• MCP Server
• Agent System
• Quality Layer
• Observability
• Architecture

Installation

# Install globally (recommended — enables `phantomind` CLI)
npm install -g @phantomind/core

# Or install as a project dependency
npm install @phantomind/core

# Verify installation
phantomind --version

Requirements: Node.js ≥ 18

Quick Start

1. Initialize in your project

cd your-project
phantomind init

This creates:

.phantomind/
  SKILLS.md       ← Auto-learned project patterns
  RULES.md        ← AI behavior rules
  schema.json     ← Output contracts
  config.yaml     ← PhantomindAI configuration

2. Sync to your AI tools

phantomind sync

Generated adapter files (auto-updated, never edit directly):

.github/copilot-instructions.md   ← GitHub Copilot
.cursorrules                      ← Cursor
.clinerules                       ← Cline
.continue/config.json             ← Continue
.windsurfrules                    ← Windsurf
.zed/settings.json                ← Zed
.aider.conf.yml                   ← Aider
.claude/CLAUDE.md                 ← Claude Code CLI
AGENTS.md                         ← OpenAI Codex CLI

3. Use the programmatic API (optional)

import { phantom } from '@phantomind/core';

await phantom.init();

// Complete with auto-routing across providers
const response = await phantom.complete('Refactor this function to use async/await');

// Run an agentic task
const result = await phantom.agent('Add input validation to the user registration endpoint');

// Semantic search across codebase
const matches = await phantom.search('authentication middleware');

CLI Reference

phantomind [command] [options]

| Command | Description | |---------|-------------| | phantomind init | Initialize PhantomindAI in the current project | | phantomind learn | Scan codebase and regenerate learned project context | | phantomind sync | Sync context to all configured AI assistant adapters | | phantomind diff | Preview adapter output diffs without writing files | | phantomind context | Preview ranked context or search context sections | | phantomind compare | Compare generated adapter payloads | | phantomind watch | Watch project files and refresh context automatically | | phantomind hooks | Install git hooks to keep context in sync | | phantomind serve | Start the MCP server (stdio or HTTP transport) | | phantomind dashboard | Start the observability dashboard server | | phantomind eval | Test and benchmark LLM provider connections | | phantomind validate [files...] | Scan code for secrets, hallucinations, and consistency issues | | phantomind audit | View cost reports and audit trail | | phantomind stats | Display project context statistics | | phantomind agent <task> | Execute an agentic task from the CLI | | phantomind schema [name] | List or display schema definitions |

phantomind init

phantomind init [options]

Options:
  --provider <name>   Optional LLM provider for agent/eval workflows
  --adapters <list>   Space-separated adapter list (e.g. copilot cursor cline)
  --template <name>   auto|default|node-library|node-cli|react-app|nextjs-app
  --yes               Skip interactive prompts

phantomind learn

phantomind learn [options]

Options:
  --sync              Run adapter sync after learning
  --verbose           Show detailed output

phantomind sync

phantomind sync [options]

Options:
  --adapters <list>   Only sync specific adapters
  --dry-run           Preview changes without writing files
  --verbose           Show per-file diff

phantomind diff

phantomind diff [options]

Options:
  --adapters <list>   Only diff specific adapters
  --verbose           Show full diff output

phantomind context

phantomind context [options]

Options:
  --file <path>       Rank context for a specific file
  --search <query>    Search across context sections
  --max-tokens <n>    Token budget for preview output
  --json              Emit raw JSON

phantomind compare

phantomind compare [options]

Options:
  --adapters <list>   Only compare specific adapters
  --preview           Show generated content preview

phantomind watch

phantomind watch [options]

Options:
  --sync              Run sync after each refresh

phantomind hooks

phantomind hooks [options]

Options:
  --force             Overwrite existing git hooks

phantomind dashboard

phantomind dashboard [options]

Options:
  --port <n>          Server port (default: 3101)
  --host <host>       Server host (default: 127.0.0.1)
  --ui <path>         Path to built dashboard assets
  --cors              Enable CORS for local development
  --token <token>     Require token for API access
  --token-env <name>  Env var containing dashboard token
  --token-query <q>   Optional query parameter name for token auth

phantomind validate

phantomind validate [files...] [options]

Options:
  --no-secrets         Skip secret scanning
  --no-hallucinations  Skip hallucination detection
  --no-consistency     Skip consistency checking
  --fix                Auto-fix detected secrets (redaction)

phantomind audit

phantomind audit [options]

Options:
  --period <p>   today|week|month|all (default: today)
  --type <t>     dashboard|costs|actions (default: dashboard)
  --format <f>   terminal|markdown|json

phantomind agent

phantomind agent <task> [options]

Options:
  --role <role>          architect|implementer|securityReviewer|testWriter|documenter
  --orchestrate          Use multi-role orchestration
  --roles <list>         Roles for orchestration (e.g. architect,implementer,testWriter)
  --max-steps <n>        Maximum agent steps (default: 30)

Configuration

PhantomindAI is configured via .phantomind/config.yaml:

# .phantomind/config.yaml

providers:
  primary:
    name: anthropic
    model: claude-opus-4-5
    apiKey: ${ANTHROPIC_API_KEY}
  fallback:
    name: openai
    model: gpt-4o
    apiKey: ${OPENAI_API_KEY}
  budget:
    name: groq
    model: llama-3.3-70b-versatile
    apiKey: ${GROQ_API_KEY}

adapters:
  - copilot
  - cursor
  - cline
  - continue
  - claude-code
  - codex

mcp:
  enabled: true
  port: 3333

budget:
  maxCostPerDay: 5.00
  warningAt: 0.80
  fallbackOnBudget: budget

agent:
  maxSteps: 30
  memory:
    enabled: true
    maxEntries: 200

quality:
  secretScanning: true
  hallucinationDetection: true
  dualVerification: false

Environment Variables

| Variable | Provider | |----------|----------| | ANTHROPIC_API_KEY | Anthropic (Claude) | | OPENAI_API_KEY | OpenAI (GPT) | | GEMINI_API_KEY | Google Gemini | | GROQ_API_KEY | Groq | | MISTRAL_API_KEY | Mistral | | DEEPSEEK_API_KEY | DeepSeek | | OPENROUTER_API_KEY | OpenRouter |

Provider-backed commands load .phantomind/.env when present. Core flows like init, learn, sync, diff, and context do not require API keys.

Dashboard UI

If you build the optional Angular dashboard package, PhantomindAI can serve both the API and the static UI:

npm run dashboard:build
phantomind dashboard

Without a built UI, phantomind dashboard still starts an API-only observability server.

Supported AI Assistants

| Adapter | File Generated | Status | |---------|---------------|--------| | GitHub Copilot | .github/copilot-instructions.md | ✅ | | Cursor | .cursorrules | ✅ | | Cline | .clinerules | ✅ | | Continue | .continue/config.json | ✅ | | Windsurf | .windsurfrules | ✅ | | Zed | .zed/settings.json | ✅ | | Aider | .aider.conf.yml | ✅ | | Claude Code | .claude/CLAUDE.md | ✅ | | OpenAI Codex | AGENTS.md | ✅ |

Supported LLM Providers

| Provider | Models | Notes | |----------|--------|-------| | Anthropic | claude-opus-4-5, claude-sonnet-4-5, claude-haiku-3-5 | Recommended primary | | OpenAI | gpt-4o, gpt-4o-mini, o3, o4-mini | Excellent fallback | | Google Gemini | gemini-2.0-flash, gemini-2.5-pro | Best for large context | | Groq | llama-3.3-70b, mixtral-8x7b | Best budget option | | Mistral | mistral-large-latest, codestral | Strong for code | | Ollama | any local model | No API key, fully local | | DeepSeek | deepseek-chat, deepseek-reasoner | Cost-efficient | | OpenRouter | 200+ models | Meta-provider |

Provider Routing

providers:
  primary:   # Highest quality — used by default
    name: anthropic
    model: claude-opus-4-5
  fallback:  # Used if primary fails
    name: openai
    model: gpt-4o
  budget:    # Used when daily cost threshold exceeded
    name: groq
    model: llama-3.3-70b-versatile
  local:     # Used for offline/sensitive tasks
    name: ollama
    model: llama3.2

Programmatic API

import { phantom } from '@phantomind/core';

// Initialize (loads config, connects providers)
await phantom.init();

// Get project context (intelligent multi-layer context)
const ctx = await phantom.ctx({ maxTokens: 4000 });

// Complete with context injection and auto-routing
const response = await phantom.complete('Explain the auth module', {
  maxTokens: 1000,
  temperature: 0.3,
});

// Complete with intelligent retry on failure
const result = await phantom.completeWithRetry('Implement JWT refresh logic');

// Run an agentic task (single role)
const agentResult = await phantom.agent('Refactor the payment service', {
  role: 'implementer',
  maxSteps: 25,
});

// Multi-agent orchestration
const orchestrated = await phantom.orchestrate(
  'Build a rate limiting middleware',
  ['architect', 'implementer', 'securityReviewer', 'testWriter'],
);

// Semantic search across codebase
const matches = await phantom.search('database connection pooling', 5);
// returns: Array<{ path, score, snippet }>

// Sync adapters
await phantom.sync(['copilot', 'cursor'], /* dryRun */ false);

// Validate code
const { secrets, hallucinations } = await phantom.validate(code, 'auth.ts');

// Cost report
const costs = phantom.costs('today'); // 'today' | 'week' | 'month' | 'all'

// Analytics dashboard
const dashboard = phantom.dashboard();
console.log(dashboard.formatTerminal());

// Learn project patterns
const skills = await phantom.learn();

// Save state
await phantom.save();

MCP Server

PhantomindAI exposes a Model Context Protocol server providing 9 tools to any MCP-compatible AI assistant:

phantomind serve

MCP Tools

| Tool | Description | |------|-------------| | get_project_context | Full project context (skills, rules, schema) | | search_codebase | Semantic search across indexed files | | validate_code | Secret + hallucination scan | | get_schema | Retrieve a named JSON/Zod schema | | list_schemas | List all registered schemas | | complete | LLM completion via provider router | | run_agent | Execute an agentic task | | get_cost_report | Current cost breakdown | | get_audit_log | Recent audit entries |

MCP Configuration (Claude Desktop / Continue)

{
  "mcpServers": {
    "phantomind": {
      "command": "npx",
      "args": ["phantomind", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

Agent System

Roles

| Role | Specialization | |------|---------------| | architect | System design, architecture decisions, dependency planning | | implementer | Feature implementation, code generation, refactoring | | securityReviewer | Vulnerability scanning, threat modeling, secure coding | | testWriter | Unit tests, integration tests, edge cases, mocks | | documenter | API docs, README, inline comments, changelogs |

Single-Agent Execution

phantomind agent "Add rate limiting to the API" --role implementer --max-steps 20

Multi-Agent Orchestration

phantomind agent "Build OAuth2 integration" --orchestrate \
  --roles architect,implementer,securityReviewer,testWriter

Quality Layer

Secret Scanning

Detects and redacts API keys, tokens, passwords, and credentials:

phantomind validate src/ --secrets

Detects: AWS keys, GitHub tokens, Stripe keys, OpenAI keys, JWT secrets, PEM certificates, database connection strings, and 20+ other patterns.

Hallucination Detection

Checks AI-generated code for:

• import statements referencing non-existent packages
• References to files that don't exist in the project
• Usage of type names not defined in the codebase

Consistency Checking

Identifies inconsistencies across the codebase:

• Naming convention violations (camelCase vs snake_case drift)
• Mixed async patterns
• Architectural boundary violations

Dual-Model Verification

For critical outputs, a second model independently verifies correctness before acceptance.

Observability

Cost Tracking

phantomind audit --type costs --period week

Tracks cost per provider, per model, per day with budget alerts.

Audit Trail

All agent actions are logged to .phantomind/audit/audit.jsonl:

phantomind audit --type actions

Analytics Dashboard

phantomind audit --type dashboard

Displays: request count, total cost, success rate, response time, quality events, agent task completion.

Architecture

packages/core/src/
├── types.ts              ← All shared TypeScript interfaces
├── index.ts              ← PhantomMind class + phantom singleton
├── config/               ← Config loading (cosmiconfig, .env, deep-merge)
├── providers/            ← LLM provider abstractions + router
├── context/              ← Project context management + semantic search
├── adapters/             ← AI assistant adapter sync (9 adapters)
├── mcp/                  ← MCP Server (9 tools)
├── agent/                ← Agentic execution engine + orchestrator
├── quality/              ← Output quality enforcement
├── schemas/              ← Schema registry (Zod + JSON Schema)
├── templates/            ← SKILLS.md + RULES.md templates
├── observability/        ← Audit, cost, dashboard
└── cli/                  ← CLI commands (Commander.js)

Roadmap

| Version | Features | |---------|---------| | v0.1 | Context sync, adapter generation, CLI init/sync | | v0.2 | Provider router, budget management, MCP server | | v0.3 | Agent executor, orchestrator, task queue | | v0.4 | Quality layer (secrets, hallucinations, consistency) | | v0.5 | Observability (audit, costs, dashboard) | | v1.0 | Schema registry, templates, stable API | | v1.x | VS Code extension, Git hooks, CI/CD integration |

License

MIT © Synaptode