How aupc2061/codehawk works
Project Type and Purpose
• CodeHawk is a CLI-based, multi-agent code analysis and editing system.
• It orchestrates planning, deep code understanding, and precise code modifications via natural-language interactions.
• Key use cases: AST-based code parsing, repository navigation, context-aware editing, human-in-the-loop validation.
File Structure and Key Components
• Top-level scripts:
• test.py – the interactive/CLI entry point
• imports.py – dependency and environment bootstrap
• setup.py & requirements.txt – packaging and dependencies
• code_agent/ directory holds the core multi-agent framework:
• main.py – initializes the LangGraph graph and CLI workflow
• routing.py – dynamic dispatch logic between agents
• core.py & config.py – global settings, TypedDict state definitions
• code_walker.py, repo_mapper.py, tree_context.py – repository and AST navigation
• tools.py – AST-based code analysis and editing utilities
• progress.py – progress monitoring, human-in-loop checkpoints
• shared_context.py & structure.py – shared state, graph node definitions
README for Architecture Insights
• Multi-Agent Workflow implemented via LangGraph directed graph.
• Three primary agents: Planner, Code Analysis, Code Editor.
• External dependencies: Anthropic, Google, Groq LLM APIs.
• Interactive CLI with Rich for text formatting and progress.
Main Components and Their Relationships
a. User Interface (CLI)
• test.py invokes main.py → Interactive session or CLI flags
• Presents model selection, workspace paths, question input
b. Planner Agent
• Entry point in the LangGraph graph
• Decomposes user request into subtasks
• Routes messages to Analysis or Editor agents via routing.py
c. Code Analysis Agent
• Uses code_walker, repo_mapper, tree_context for AST parsing and file search
• Identifies relevant files, functions, classes
• Returns structured context to Planner
d. Code Editor Agent
• Uses tools.py and structure.py to perform modifications
• Preserves formatting and encoding, runs error checks
• Passes proposed changes back for human validation
e. Human-in-the-Loop Validation
• progress.py handles interactive approval steps
• Allows accept/reject before final write-back
f. External LLM Services
• LangChain-Anthropic for Claude-3
• LangChain-Google for Gemini 2.0
• Groq for LLaMA 70B
• Agent nodes call APIs, receive completions
g. State Management
• shared_context.py holds conversation history and intermediate data
• TypedDict structures ensure consistent state across graph nodes
Architectural Patterns and Design Principles
• Directed Graph (LangGraph) for orchestration
• Separation of concerns: Planning, Analysis, Editing
• Plugin-style tools: code_walker, AST utilities, repo_mapper
• Human-in-the-loop gating for safety
• Typed state objects for reliability
Final Checklist
• Clear, descriptive labels for every component
• Boundaries showing workspace file system vs. in-memory state
• Annotation of major frameworks: LangGraph, LangChain, Rich, AST