deep-analysis

Deep Analysis CLI

A CLI tool for systematic deep analysis of markdown documents and codebases using a two-tier AI architecture: a researcher model for reasoning and a scout model for file discovery.

🤖 Note: This project was "vibe engineered" with Amp and Claude Opus 4.5 and others as part of my ongoing effort to demonstrate that AI-assisted development can produce high-quality software when paired with rigorous design documentation, comprehensive tests, and careful human review.

Features

• Two-Tier Architecture: The researcher model focuses on reasoning while the scout model handles file discovery
• OpenAI and Anthropic: Run the same workflow with GPT or Claude models, including Fable and Opus
• Three High-Level Tools: find_files, summarize_files, read_files with cost controls
• Session Continuity: Continue conversations with --continue <session-id>
• Cost Tracking: Separate usage reporting for researcher and scout models

Prerequisites

• mise for the pinned Go and CLI toolchain in mise.toml
• Go 1.26.0 or later if building without mise
• An OpenAI API key or Anthropic API key, depending on the selected provider

Installation

mise install

# Build the CLI with the pinned toolchain
mise run build

# Install into your Go bin dir
mise run install

# Install into ~/bin
mise run install:global

# Or directly with Go if you already have it installed
mkdir -p dist
go build -o dist/deep-analysis .

Configuration

Set your OpenAI API key with an environment variable:

export OPENAI_API_KEY="your-api-key-here"

For Anthropic models, use:

export ANTHROPIC_API_KEY="your-api-key-here"

Or store it in an XDG config file:

./dist/deep-analysis setup

# Or configure Anthropic
./dist/deep-analysis setup --provider anthropic

The shared config stores keys as openai_api_key and anthropic_api_key. deep-analysis also checks the provider-specific ${XDG_CONFIG_HOME:-$HOME/.config}/openai/config.yaml and anthropic/config.yaml files, where api_key is accepted. Environment variables take precedence for credentials.

Set global researcher and scout defaults in the shared config so every run can use the same provider mix:

researcher: anthropic.claude-opus-4-8@xhigh
scout: openai.gpt-5.5@low

These fields can live alongside the API keys. Model selection precedence is command-line flag, then global config, then the compiled OpenAI defaults. Running setup to add or replace a provider key preserves the configured model defaults.

Check the installed binary, effective models, and credential sources:

./dist/deep-analysis doctor

Usage

Basic Analysis

# Analyze a markdown document (results appended in place)
./dist/deep-analysis notes.md

# Write output to a different file
./dist/deep-analysis notes.md --output annotated.md

# Analyze a project in a different directory
./dist/deep-analysis --cwd /path/to/project task.md

# Use Fable 5 for research and Sonnet 5 for scouting
./dist/deep-analysis task.md \
  --researcher anthropic.claude-fable-5@xhigh \
  --scout anthropic.claude-sonnet-5@low

# Use Opus as the researcher instead
./dist/deep-analysis task.md \
  --researcher anthropic.claude-opus-4-8@xhigh \
  --scout anthropic.claude-sonnet-5@low

# Mix providers: Fable researcher with an OpenAI scout
./dist/deep-analysis task.md \
  --researcher anthropic.claude-fable-5@xhigh \
  --scout openai.gpt-5.5@low

# Or GPT researcher with an Anthropic scout
./dist/deep-analysis task.md \
  --researcher openai.gpt-5.6-sol@xhigh \
  --scout anthropic.claude-sonnet-5@low

Selections use provider.model[@effort]. The provider is split at the first dot and optional effort at the final @; accepted efforts are low, medium, high, and xhigh. Omit the suffix to use the provider's model default. OpenAI GPT-5.6 researchers use Pro mode while older OpenAI overrides retain their existing request behavior. @ needs no escaping in common shells or YAML.

Follow-up Questions

Each run generates a session ID logged to stderr:

INFO Saved session session=f1736654e6d5a7c1b58d14ac response_id=resp_xxx

To continue a conversation:

1. Add your follow-up question to the document
2. Run with --continue:

./dist/deep-analysis notes.md --continue f1736654e6d5a7c1b58d14ac

The AI will see your previous analysis and focus on new questions.

CLI Flags

Commands

How It Works

Two-Tier Architecture

Researcher model           →  Reasoning, analysis, conclusions
        ↓
    find_files / summarize_files / read_files
        ↓
Scout model                →  Translates queries to glob/grep
        ↓
File System                →  Actual file access

Tools Available to the Researcher

1. find_files(query, paths) - Discover files matching natural language intent

   • Returns file paths with sizes
   • Scout translates to glob/grep patterns

2. summarize_files(paths, focus) - Get AI-generated summaries (cheap, use liberally)

   • Scout reads and summarizes files
   • Use for triage before full reads

3. read_files(paths) - Read full file contents (expensive, use sparingly)

   • Limited to 10 files or 200KB per call
   • Exceeding limits returns an error with guidance

Workflow

The researcher follows: find → summarize → read

1. find_files("error handling") → Returns 15 files (180KB total)
2. summarize_files(all paths, "error patterns") → Quick summaries
3. Identify 3 key files from summaries
4. read_files(those 3) → Full content for analysis
5. Write analysis citing specific code

Cost Tracking

Each run reports usage for both models:

INFO Researcher usage model=gpt-5.6-sol api_calls=5 input_tokens=12000 uncached_input_tokens=4000 output_tokens=3000 cached_tokens=7000 cache_write_tokens=1000 cache_hit_rate=58.3% cost_usd=$0.1198
INFO Scout usage      model=gpt-5.5     api_calls=8 input_tokens=45000 output_tokens=800 cost_usd=$0.2490
INFO Total cost               usd=$0.3688

OpenAI GPT-5.6 researcher requests keep the same instructions, tools, reasoning settings, and model-scoped cache key through the tool loop. Their usage line separates uncached input, cache writes, and cache reads so the hit rate and GPT-5.6 cache-write premium are visible in the cost estimate.

Anthropic researcher runs automatically cache the growing tool-use conversation for five minutes. Their usage line also reports fresh input, cache creation, cache reads, and the resulting cache hit rate so the cost estimate includes Anthropic's cache-write premiums.

Development

mise run build  # Build to dist/deep-analysis
mise run install  # Install to GOBIN or GOPATH/bin
mise run install:global  # Install to ~/bin
mise run test   # Run tests
mise run lint   # Run linter
mise run run notes.md
mise run run notes.md --output annotated.md

Architecture

.
├── main.go                      # CLI entrypoint
├── internal/
│   ├── agent/
│   │   ├── scout.go            # Scout dispatcher default
│   │   ├── manifest.go         # Project file listing
│   │   └── file_search.go      # Legacy file search
│   ├── client/
│   │   ├── deepanalysis.go     # OpenAI researcher and shared workflow
│   │   ├── anthropic.go        # Anthropic researcher tool loop
│   │   └── session_store.go    # Session persistence
│   ├── fileops/
│   │   └── fileops.go          # File operations (read, grep, glob)
│   └── server/                 # MCP server (optional)
└── plans/
    └── two-tier-analysis.md    # Architecture documentation

License

MIT