Skip to content

CLAUDE.md

Latest commit

 

History

History
135 lines (109 loc) · 5.37 KB

CLAUDE.md

File metadata and controls

135 lines (109 loc) · 5.37 KB

Limo CLI - Development Guide

Project Overview

Limo CLI is an AI-powered code analysis tool built with the Deity framework and GitHub Copilot SDK.

Architecture

Multi-Agent Workflow

Limo uses a 4-phase analysis pipeline defined as a declarative TSX workflow:

<Workflow name="limo-analysis-workflow" defaultModel={{ adapter: llmAdapter }}>
  <Sequence>
    <PlannerAgent promptsDir={promptsDir} createTools={createPlannerTools} />
    <ForEach items={getTasks} itemMode="property" itemKey="task" errorMode="continue">
      <AnalystAgent promptsDir={promptsDir} createTools={createAnalystTools} />
    </ForEach>
    <ForEach items={getTasks} itemMode="property" itemKey="task" errorMode="continue">
      <WriterAgent promptsDir={promptsDir} createTools={createWriterTools} />
    </ForEach>
    <EditorAgent promptsDir={promptsDir} createTools={createEditorTools} />
  </Sequence>
</Workflow>

Key Design Decisions

1. Disposable Session Pattern

  • Create a new Copilot SDK session for each generate() call
  • Destroy session immediately after request completes via finally block
  • Deity is stateless by design, using intelligent memory instead of session history

2. Tool Invocation Strategy

  • Deity passes tools to LLM adapter; adapter decides implementation
  • Copilot SDK uses defineTool() and handles the tool invocation loop
  • onPostToolUse hook tracks tool call history for Deity compatibility
  • excludedTools blocks all environment tools (bash, powershell, view, etc.)

3. Tool Scope

  • Generic tools (file_list, file_read, web_search): shared across agents
  • Specialized tools (planning_create, memory_store, report_write): agent-specific
  • Each agent gets a filtered subset via Tool Factory Pattern: createTools: (ctx: ExecutionContext) => Tool[]

4. Validator Pattern

  • Deity's Validator interface separates tool execution from task completion validation
  • SDK handles execution, Deity controls the LLM loop, validators check completion criteria
  • Validators provide feedback to guide LLM convergence across multiple rounds

Output Extraction

Since SDK handles tools internally, extractOutput extracts results from the final LLM response (JSON in markdown code blocks) or from tool call history tracked via hooks.

Dependencies

@limo-labs/deity@^0.2.2
@limo-labs/deity-adapter-copilot@^0.2.2
@limo-labs/deity-tools@^0.2.1
@github/copilot-sdk@^0.1.29
zod@^4.3.6

Project Structure

src/
├── index.ts                    # CLI entry point
├── commands/
│   ├── analyze.tsx             # Main analyze command (orchestration + TUI)
│   ├── analyze-init.ts         # Initialization logic
│   ├── analyze-workflow.tsx     # Workflow definition
│   └── analyze-save.ts         # Result saving logic
├── agents/
│   ├── planner.tsx             # Planner agent (JSX component)
│   ├── analyst.tsx             # Analyst agent (JSX component)
│   ├── writer.tsx              # Writer agent (JSX component)
│   ├── editor.tsx              # Editor agent (JSX component)
│   └── planner-validator.ts    # Planner validation logic
├── tools/
│   ├── index.ts                # Tool registry and factory
│   ├── planning.tsx            # Planning tools
│   ├── report.tsx              # Report writing tools
│   ├── task.tsx                # Task management tools
│   └── code-analysis.tsx       # Code analysis tools
├── tui/                        # Terminal UI (Ink/React)
│   ├── app.tsx                 # Main TUI application
│   ├── renderer.ts             # Ink renderer
│   ├── console-fallback.ts     # Non-TUI fallback
│   ├── progress-tracker.ts     # Progress tracking
│   ├── types.ts                # TUI type definitions
│   └── components/
│       ├── header.tsx
│       ├── task-log.tsx
│       ├── status-panel.tsx
│       └── stream-preview.tsx
├── report/
│   ├── diagrams.ts             # Diagram generation
│   ├── graphCompiler.ts        # Graph compilation
│   └── markdownGenerator.ts    # Markdown report generation
├── types/
│   └── graphSemantics.ts       # Graph semantic types
└── utils/
    ├── debug.ts                # Debug logging (LIMO_DEBUG env var)
    ├── limoConfigParser.ts     # LIMO.md config parser
    └── reviewMonitor.ts        # Review monitoring
prompts/
├── planner.md                  # Planner system prompt
├── analyst.md                  # Analyst system prompt
├── writer.md                   # Writer system prompt
└── editor.md                   # Editor system prompt

Build & Run

npm run build          # TypeScript compilation
npm run dev            # Build + run
npm run analyze        # Build + run analyze command

# Example usage
node dist/index.js analyze . --modules architecture --output .limo
node dist/index.js analyze . --modules architecture,code-quality --lang English

Debugging

  • Set LIMO_DEBUG=1 environment variable for debug logging
  • Use --debug-api flag to see Copilot SDK adapter debug output
  • Use --verbose flag for detailed progress output