cli_engineer 0.4.1

An experimental autonomous CLI coding agent
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

# Architecture Documentation

## System Overview
The **cli_engineer** is a Rust-based, non-interactive CLI tool that leverages AI to automate coding tasks. It manages artifacts (e.g., code files, execution outputs), executes code in isolated environments, installs dependencies, maintains an artifact manifest, and provides a colorful terminal display with real-time feedback. The tool is designed for fully automated execution, relying on initial commands and configurations without requiring user interaction.

## Key Components

### 1. CLI Interface
- **Purpose**: Parses initial user commands and displays outputs.
- **Responsibilities**: 
  - Accepts input via CLI flags or TOML configuration files.
  - Delegates tasks to the Task Orchestrator.
  - Displays the artifact manifest and execution results.

### 2. Task Orchestrator
- **Purpose**: Coordinates automated workflows based on initial input and configurations.
- **Responsibilities**: 
  - Manages task execution (e.g., code generation, search, compression) based on predefined rules.
  - Orchestrates parallel tasks and synthesizes results.
  - Emits events for progress, completion, and metrics to the Event Bus.
  - Prioritizes tasks based on initial configuration or command parameters.

### 3. AI Integration Layer
- **Purpose**: Abstracts interactions with AI providers.
- **Responsibilities**: 
  - Supports providers like Anthropic, OpenAI, Gemini, xAI, OpenRouter, and Ollama.
  - Switches between reasoning, non-reasoning, and visual analysis models based on task requirements.
  - Tracks API costs and emits metrics.
  - Optimizes prompts for precise code-related queries.

### 4. Codebase Interaction Module
- **Purpose**: Facilitates intelligent, automated interaction with the codebase.
- **Responsibilities**: 
  - Performs agentic search using AI-driven queries to locate relevant code or documentation.
  - Executes shell commands (e.g., `ls`, `cat`, `grep`, `find`) and captures outputs.
  - Implements semantic code search with fuzzy matching and cross-file context analysis.
  - Supports automated file operations (create, read, update, delete) with AI validation.

### 5. Artifact and Execution Manager
- **Purpose**: Manages artifacts, execution environments, and dependencies.
- **Responsibilities**: 
  - Creates and stores artifacts (e.g., code files, outputs).
  - Sets up isolated execution environments (e.g., Python virtualenv, containers).
  - Installs dependencies using AI-driven detection or explicit requirements.
  - Maintains a JSON artifact manifest with metadata (name, type, location, creation time, purpose).
  - Emits events for progress and completion.
  - Validates artifact integrity post-execution (e.g., syntax checks, linting).
  - Generates execution plans for complex tasks before running code.

### 6. Context Manager
- **Purpose**: Tracks and optimizes context usage for AI models.
- **Responsibilities**: 
  - Monitors context window size and usage.
  - Compresses context via summarization at 50% usage.
  - Emits context usage metrics.
  - Caches frequently used context snippets for faster retrieval.

### 7. MCP and Visual Analysis Module
- **Purpose**: Integrates with MCP servers and processes visual data.
- **Responsibilities**: 
  - Acts as an MCP client for tool access (e.g., Playwright for UI screenshots).
  - Analyzes images with a visual analysis model (VLM/multimodal LLM).
  - Supports web content retrieval for documentation or API reference.

### 8. Quality and Collaboration Module
- **Purpose**: Enhances code quality and supports collaboration.
- **Responsibilities**: 
  - Performs AI-driven semantic linting with customizable rules.
  - Integrates with GitHub for issue and pull request management.
  - Suggests code refactorings based on best practices.

### 9. Parallel Task Handler
- **Purpose**: Manages concurrent task execution.
- **Responsibilities**: 
  - Executes tasks in parallel using `tokio`.
  - Synthesizes results for the Task Orchestrator.
  - Prioritizes parallel tasks based on estimated impact.

### 10. Terminal UI Module
- **Purpose**: Provides a visually appealing terminal display for automated processes.
- **Responsibilities**: 
  - Renders colorful output using ANSI escape codes.
  - Displays progress bars (via `indicatif`) for tasks like execution and dependency installation.
  - Shows real-time metrics (context usage, API costs, run time).
  - Updates based on Event Bus events.
  - Displays a summary of the artifact manifest in a tabulated format.

### 11. Event Bus
- **Purpose**: Facilitates communication between components.
- **Responsibilities**: 
  - Receives events (e.g., "artifact_created", "execution_progress").
  - Forwards events to the Terminal UI Module and other components.

## Key Flows

### Artifact Management Flow
1. The **Task Orchestrator** initiates artifact creation or execution based on initial commands and configurations.
2. The **Artifact and Execution Manager**: 
   - Sets up an isolated environment and installs dependencies.
   - Executes code, validates outputs, and stores artifacts.
   - Updates the manifest and emits events.
3. The **Terminal UI Module** displays progress bars and the artifact manifest.

### Terminal Display Mechanism
1. Components emit events to the **Event Bus** (e.g., "context_usage", "api_cost").
2. The **Terminal UI Module** renders:
   - Color-coded sections ([Artifacts], [Execution], [Metrics]).
   - Progress bars for tasks.
   - Real-time metrics and manifest summary.

**Example Terminal Output**:
```
[Artifacts]
- main.py (created at 2025-05-16 16:34)
- output.txt (generated at 2025-05-16 16:35)

[Execution]
- Running task: [=====     ] 50% complete

[Metrics]
- Context Usage: 30% (3000/10000 tokens)
- API Cost: $0.05
- Run Time: 5 minutes
```

## Technologies
- **Language**: Rust
- **CLI Framework**: `clap`
- **Async Programming**: `tokio`
- **HTTP Client**: `reqwest`
- **Serialization**: `serde`
- **Terminal UI**: `indicatif` for progress bars, custom ANSI rendering
- **Testing**: `cargo test`

## Design Principles
- **Modularity**: Components interact via the Event Bus.
- **Extensibility**: Easy to add providers or tools.
- **Safety**: Isolated execution and Rust’s memory safety.
- **Automation**: Executes tasks without user intervention based on initial input.