Phoenix CLI

Every project has a story. Phoenix finds it.

Phoenix CLI is an open-source Project Intelligence Framework that helps developers and AI coding assistants understand existing software projects before attempting to change them.

Why Phoenix?

Software projects don't fail because the code disappears — they fail because the intent disappears. The original architect leaves. Design rationale is never documented. READMEs go stale. The last person who knew the conventions just resigned.

Phoenix recovers that lost context. It reads your codebase, extracts signals (entry points, dependencies, conventions, patterns, risks), and produces structured intelligence artifacts — all without modifying a single line of source code.

Quick Start

Prerequisites

• Node.js >= 22.12.0
• npm or a compatible package manager

Installation

npm install -g phoenix-cli-tool

Or run directly with npx:

npx phoenix awaken

Usage

# Analyse the current directory
npx phoenix awaken

# Analyse a specific project
npx phoenix awaken ../legacy-app

# Generate a structured debate about the architecture
npx phoenix council --topic architecture

# Recreate missing documentation
npx phoenix rebuild

Commands

Phoenix ships exactly three commands in the MVP:

phoenix awaken

Recover project understanding from source signals.

phoenix awaken [path] [--depth <n>] [--verbose]

| Option | Default | Description | | ----------- | ------- | --------------------------------- | | [path] | . | Directory to analyse | | --depth | 3 | Maximum directory traversal depth | | --verbose | false | Enable verbose logging |

What it produces:

• A Project Intelligence Report with architecture summary, entry points, dependency map, conventions, risks, and confidence scores
• Stored in .phoenix/reports/ for future use

phoenix council

Generate a structured debate between multiple expert personas.

phoenix council [path] [--topic <topic>] [--personas <n>]

| Option | Default | Description | | ------------ | ------- | -------------------------------------- | | [path] | . | Project root | | --topic | — | Focus the debate (e.g. architecture) | | --personas | 4 | Number of personas (3-5) |

What it produces:

• A Council Debate with opening statements, disagreements, cross-examination, and synthesis with recommended actions

phoenix rebuild

Recreate missing project documentation from recovered intelligence.

phoenix rebuild [path] [--only <scope>] [--agents <list>] [--force] [--dry-run]

| Option | Default | Description | | ----------- | -------- | ---------------------------------------------------- | | [path] | . | Project root | | --only | all | Limit scope: docs, agents, contributing, all | | --agents | claude | AI context files to generate (comma-separated) | | --force | false | Overwrite existing files | | --dry-run | false | Preview without writing |

What it produces:

• Documentation files (docs/ARCHITECTURE.md, docs/CONTRIBUTING.md, etc.)
• AI context files (CLAUDE.md, AGENTS.md, .cursorrules)

How It Works

┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│  phoenix awaken  │ ──── │ Intelligence     │ ──── │ .phoenix/       │
│  (Recover)       │      │ Report           │      │ (stored)        │
└─────────────────┘      └──────────────────┘      └─────────────────┘
                               │         │
                               │         │
                    ┌──────────┘         └──────────┐
                    ▼                               ▼
         ┌──────────────────┐            ┌──────────────────┐
         │ phoenix council   │            │ phoenix rebuild   │
         │ (Challenge)       │            │ (Document)        │
         └──────────────────┘            └──────────────────┘
                    │                               │
                    ▼                               ▼
         ┌──────────────────┐            ┌──────────────────┐
         │ Council Debate   │            │ docs/ + AI ctx   │
         │ (disagreements)  │            │ (CLAUDE.md, etc) │
         └──────────────────┘            └──────────────────┘

Architecture

Phoenix CLI is built as a strictly layered architecture:

| Layer | Purpose | | ------------- | ------------------------------------------------------------------ | | CLI | Thin user-facing shell (commander, arguments) | | Core | Provider-agnostic domain logic, schemas, ports | | Engines | Intelligence pipelines (Discovery, Council, Documentation, Memory) | | Providers | Optional AI compute abstraction | | Storage | .phoenix/ directory management |

Key Principles

• Understand before changing — Phoenix never modifies source code
• Provider agnostic — Core never depends on any AI provider SDK
• Offline by default — No network calls required for core commands
• Structured data first — All output is JSON-constrained by schemas
• Determinism — Same input + same version = same output

Dependency Budget

Phoenix maintains a minimal dependency footprint:

| Runtime Dependencies | Purpose | | -------------------- | --------------- | | chalk | Terminal colors | | commander | CLI framework | | ora | Spinners |

Project Structure

phoenix-cli-tool/
├── src/
│   ├── index.ts                 # Entry point
│   ├── cli.ts                   # CLI layer
│   ├── constants.ts             # App metadata
│   ├── commands/                # One file per command
│   │   ├── awaken.ts
│   │   ├── council.ts
│   │   └── rebuild.ts
│   ├── core/                    # Domain logic
│   │   ├── project.ts
│   │   ├── scanner.ts
│   │   ├── schema/              # Runtime validation
│   │   ├── signals/             # Signal extraction
│   │   └── ports/               # Interfaces (Storage, Provider, Logger)
│   ├── engines/                 # Intelligence pipelines
│   │   ├── discovery/
│   │   ├── council/
│   │   ├── documentation/
│   │   └── memory/
│   ├── providers/               # AI provider abstraction
│   ├── storage/                 # .phoenix/ management
│   ├── templates/               # Document templates
│   └── report/                  # JSON/Markdown serializers
├── tests/                       # Vitest test suites
├── docs/                        # Project documentation
├── phoenix.schema.json          # Specification schema
├── package.json
├── tsconfig.json
└── README.md

Configuration

Phoenix reads configuration from phoenix.json at the project root. When absent, sensible defaults are used.

Example phoenix.json:

{
  "project": {
    "name": "my-project"
  },
  "engines": {
    "council": {
      "personas": 4,
      "defaultTopic": "architecture"
    }
  },
  "providers": {
    "default": "noop",
    "adapters": {
      "claude": {
        "enabled": false
      }
    }
  }
}

The .phoenix/ Directory

Phoenix stores all intelligence artifacts in a .phoenix/ directory within your project:

.phoenix/
├── phoenix.json              # Project configuration
├── memory/
│   └── snapshot.json         # Signals for diffing across runs
├── reports/
│   └── <id>/
│       ├── report.json       # Canonical Intelligence Report
│       └── meta.json         # Run metadata
├── artifacts/
│   └── council/
│       └── <id>/
│           ├── debate.json   # Council Debate
│           └── debate.md     # Human-readable rendering
└── history/
    └── <id>.json             # Command execution history

Testing

Phoenix uses Vitest for testing:

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run type checks
npm run typecheck

# Lint the codebase
npm run lint

Test Layers

| Layer | Scope | | ----------- | ------------------------------------------------- | | Unit | Pure core logic, schemas, serializers | | Integration | Engine pipelines against fixture projects | | E2E | Built binary on sample repos; exit codes + output |

Exit Codes

| Code | Meaning | | ---- | ------------------------------------------ | | 0 | Success | | 1 | General failure (exception, IO error) | | 2 | Invalid arguments / unknown command | | 3 | Schema validation failure | | 4 | Target project not found / not a directory |

AI Provider Support

Phoenix is provider-agnostic but can optionally use AI providers for richer analysis:

| Provider | Context File | Status | | -------- | ---------------- | --------- | | Claude | CLAUDE.md | Supported | | OpenCode | AGENTS.md | Supported | | Cursor | .cursorrules | Supported | | Codex | codex.md | Supported | | Gemini | GEMINI.md | Supported | | Aider | CONVENTIONS.md | Supported |

By default, Phoenix operates fully offline with heuristic analysis. Provider adapters are opt-in and isolated behind an interface.

Documentation

| Document | Description | | ----------------------------------------- | ------------------------------------- | | PRD.md | Product requirements and principles | | ARCHITECTURE.md | Layered architecture details | | COMMANDS.md | Full command reference | | ENGINES.md | Per-engine specifications | | SPECIFICATION.md | .phoenix/ file format specification | | ROADMAP.md | Version milestones and future vision | | DECISIONS.md | Architecture Decision Records | | CONTRIBUTING.md | How to contribute |

Roadmap

| Version | Milestone | | ---------- | ------------------------------------------------- | | v1.0.0 | MVP — awaken, council, rebuild | | v2.0.0 | Memory & Evolution engines, monorepo support | | v3.0.0 | Plugin ecosystem, Builder engine, IDE integration |

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

Development

# Install dependencies
npm install

# Start development mode
npm run dev

# Run the CLI directly
npm run phoenix

# Format code
npm run format

# Check boundaries
npm run check:boundaries

License

This project is licensed under the ISC License — see the LICENSE file for details.

Acknowledgments

Phoenix CLI was built with the understanding that every codebase has a story worth recovering. It is designed to be the layer of understanding that makes all code generation safer.

Star this repo if you believe in understanding before changing.