# Gemini CLI: Architectural Codebase Review & Recommendations
**Date:** March 6, 2026
**Scope:** Core Agent Architecture (`src/agent/`)
After reviewing the codebase and existing reviews (`COMPREHENSIVE_PROJECT_REVIEW.md`, `DEEP_DIVE_REVIEW.md`), I've conducted an analysis focusing on the structural and architectural integrity of the core system. The Selfware project has a robust foundation, but as it has grown, several critical code hotspots have emerged that require refactoring to ensure long-term maintainability.
## 1. The `Agent` Struct (God Object Anti-Pattern)
**Location:** `src/agent/mod.rs`
The `Agent` struct has become a classic "God Object." It currently holds over 20 fields and manages disparate responsibilities:
- API client communication (`client`)
- Tool registry and execution (`tools`)
- Safety checking (`safety`)
- Memory and history (`memory`, `edit_history`, `chat_store`)
- Cognitive state and self-improvement (`cognitive_state`, `self_improvement`)
- Verification and Error Analysis (`verification_gate`, `error_analyzer`)
- TUI Events (`events`)
**Recommendation:**
Decompose the `Agent` into specialized sub-components. For example:
- `ToolOrchestrator`: Owns `tools`, `safety`, and execution logic.
- `ContextManager`: Owns `memory`, `context_files`, `compressor`, and `messages`.
- `CognitiveEngine`: Owns `cognitive_state`, `self_improvement`, and `error_analyzer`.
The core `Agent` should solely act as a lightweight coordinator delegating to these domain managers.
## 2. Execution Logic & Middleware Interceptors
**Location:** `src/agent/execution.rs`
Functions like `execute_step_internal` perform heavy lifting and mix concerns. For instance, `detect_and_correct_malformed_tools` and `detect_repetition` are hardcoded directly into the main execution pipeline.
**Recommendation:**
Implement a **Middleware / Interceptor Pattern** for the execution pipeline. Pre-execution checks (like repetition detection, malformed tool correction) should be separate middlewares that run over the generated tool calls. This allows easily plugging in new safety checks or heuristics without modifying the core execution loop.
## 3. Formalizing Cognitive Phases
**Location:** `src/agent/task_runner.rs`
The state machine in `task_runner.rs` transitions between `AgentState::Planning`, `AgentState::Executing`, and `AgentState::ErrorRecovery`. Currently, phase transitions (Plan -> Do -> Verify -> Reflect) are managed via manual mutations (`self.cognitive_state.set_phase(CyclePhase::Plan)`).
**Recommendation:**
Adopt the **Typestate Pattern** or a formalized State Machine for cognitive phases. Transitions should yield new types (e.g., `PlanningAgent` transitions to `ExecutingAgent`), ensuring that operations valid only in one phase cannot be executed in another at compile time, eliminating a class of runtime state errors.
## 4. Decoupling Core Logic from UI/TUI Events
**Location:** `src/agent/mod.rs` & `src/agent/execution.rs`
The core agent logic directly calls `self.emit_event(AgentEvent::...)` and interacts with the UI spinner logic. This tightly couples the agent's domain logic to the presentation layer.
**Recommendation:**
Introduce an asynchronous **Event Bus / PubSub mechanism**. The agent should simply dispatch domain events (`ToolExecutionStarted`, `TaskPlanned`) to an event stream. The `ui` module should run as a separate subscriber to this stream, interpreting the events to update spinners, progress bars, or the TUI dashboard. This will significantly improve the testability of the core logic.
## 5. Extensibility of Tool Calling Formats
**Location:** `src/agent/execution.rs`
The logic heavily branches based on `self.config.agent.native_function_calling`. The mixing of XML fallback parsing and Native Tool calls clutters functions like `collect_tool_calls` and `push_tool_result_message`.
**Recommendation:**
Abstract tool calling strategies into an interface (e.g., `ToolCallingStrategy`). Provide a `NativeToolStrategy` and an `XmlToolStrategy`. This will abstract away the parsing and formatting idiosyncrasies, simplifying the agent's interaction loop and making it easier to support new LLM backends or parsing formats in the future.
---
*Generated by Gemini CLI in autonomous mode.*