Skip to content

COMMANDCODE.md

Latest commit

 

History

History
186 lines (134 loc) · 6.55 KB

COMMANDCODE.md

File metadata and controls

186 lines (134 loc) · 6.55 KB
Raw

LeanKG - AI Agent Context

Project Overview

LeanKG is a lightweight knowledge graph for codebase understanding. It indexes code, builds dependency graphs, calculates impact radius, and exposes everything via MCP for AI tool integration.

Tech Stack: Rust + CozoDB + tree-sitter + MCP

Quick Start

# Index a codebase
cargo run -- init
cargo run -- index ./src

# Calculate impact radius
cargo run -- impact src/main.rs 3

# Start MCP server
cargo run -- serve

Development Workflow

When implementing features, follow: docs/workflow-opencode-agent.md

Pattern: Update Docs -> Implement -> Test -> Commit -> Push -> Bump Version -> Tag

  1. Update docs first - PRD (docs/requirement/prd-leankg.md) -> HLD (docs/design/hld-leankg.md) -> README
  2. Implement - Follow patterns in docs/workflow-opencode-agent.md
  3. Build & test - cargo build && cargo test
  4. Commit - git commit -m "feat: description" (one feature per commit)
  5. Push - git pull --rebase && git push
  6. Bump version - Update version in Cargo.toml
  7. Tag - git tag -a v<version> -m "Release v<version>" && git push origin v<version> (after version bump)

Commit Message Rules

  • NEVER add Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> to commits
  • NEVER add 🤖 Generated with Claude Code or similar AI attribution
  • NEVER add "Generated by" phrases in PR descriptions
  • Use Co-authored-by: CommandCodeBot noreply@commandcode.ai when explicitly requested

Parallel Subagent Workflow

When facing 3+ independent tasks that can work in parallel without shared state:

  1. Dispatch multiple subagents - One agent per independent problem domain
  2. Each agent works in isolated .worktree/ - Prevents interference between agents
  3. Each worktree uses feature branch - Format: .worktree/<feature-name>/
  4. Verify isolation - Confirm directory is in .gitignore
  5. Run baseline tests - Ensure clean starting point per worktree
  6. Agent completes independently - Agent returns summary of changes
  7. Merge to main - After all agents complete, merge each feature branch to main
# Example workflow
Agent 1 -> .worktree/feature-a/ (works on tests in file_a.test.ts)
Agent 2 -> .worktree/feature-b/ (works on tests in file_b.test.ts)
Agent 3 -> .worktree/feature-c/ (works on tests in file_c.test.ts)

# After all complete
git checkout main
git merge feature-a
git merge feature-b
git merge feature-c
git push

When to use:

  • 3+ test files failing with different root causes
  • Multiple subsystems broken independently
  • Each problem can be understood without context from others

When NOT to use:

  • Failures are related (fix one might fix others)
  • Need to understand full system state
  • Agents would interfere with each other

Key Commands

IMPORTANT: Always use --release flag for builds. Debug builds are disabled.

cargo build --release  # Build project (release)
cargo test             # Run tests
cargo run --release -- <cmd>  # Run CLI commands

UI Development

The UI is a Vite + React app in ui/:

cd ui && npm run dev    # Dev server at http://localhost:5173/ (hot reload)
cd ui && npm run build  # Production build

Workflow after testing:

cp -r ui/dist/* src/embed/
cargo build --release  # Rebuild Rust with new UI assets

For full backend testing:

cargo run -- serve      # Backend API at http://localhost:8080/
# Then open http://localhost:8080 in browser

Important Files

File Purpose
src/lib.rs Module exports
src/db/models.rs Data models (CodeElement, Relationship, BusinessLogic, RelationshipType)
src/graph/query.rs Graph query engine
src/mcp/tools.rs MCP tool definitions
src/mcp/handler.rs MCP tool handlers
src/indexer/extractor.rs Code parsing with tree-sitter
src/indexer/microservice.rs Microservice gRPC call extraction
config/microservice-extractor.yaml Default rules for microservice relationship extraction

Data Model

  • CodeElement - Files, functions, classes with qualified_name (e.g., src/main.rs::main)
  • Relationship - imports, calls, tested_by, references, documented_by, service_calls
  • ServiceCalls - Microservice gRPC calls between services via DNS addresses
  • BusinessLogic - Annotations linking code to business requirements

MCP Tools

Core tools: query_file, get_dependencies, get_dependents, get_impact_radius, get_review_context, find_function, get_call_graph, search_code, generate_doc, find_large_functions, get_tested_by

Doc/Traceability tools: get_files_for_doc, get_doc_tree, get_traceability, search_by_requirement, get_code_tree, find_related_docs

Cluster tools: get_clusters, get_cluster_context

Risk tools: detect_changes

Known Limitations

  • Android/Kotlin/XML search - Search for Android-related code elements (Kotlin, XML layouts, AndroidManifest.xml) may return incomplete results. The indexer finds these files but search indexing has gaps.

Verification Status

See docs/implementation-feature-verification-2026-03-25.md for test results.

LeanKG Tools Usage

MANDATORY: Use LeanKG First, Fallback to Raw Tools

This is a MANDATORY workflow - not optional guidance.

Step 1: Always Try LeanKG First

  1. Call mcp_status to check if LeanKG is ready
  2. If not ready, call mcp_init with path: "/Users/linh.doan/work/harvey/freepeak/leankg/.leankg"
  3. Use appropriate LeanKG tool: search_code, find_function, query_file, get_impact_radius, get_dependencies, get_dependents, get_tested_by, get_context

Step 2: Fallback Only If LeanKG Fails

  • LeanKG returns empty results OR
  • LeanKG returns error AND you need the data
  • THEN you may use Glob, Grep, Read as fallback

Step 3: Never Skip LeanKG for Code Search

  • NEVER say "I'll just use grep" without trying LeanKG first
  • NEVER claim "LeanKG doesn't have this" without actually checking
Task LeanKG First Fallback
Where is X? search_code("X") Grep("X")
Find function find_function("name") Grep("fn name")
What breaks? get_impact_radius(file) Manual trace
What tests? get_tested_by(file) Grep("test.*file")
Read content get_context(file) Read(file)

Why This Matters

  • LeanKG is 10-100x faster than raw grep on large codebases
  • LeanKG understands code relationships (imports, calls, tests)
  • Raw tools should be emergency fallback only

Last updated: 2026-05-04