From be54032cd8003c92a1e09c31b13df68c6174695c Mon Sep 17 00:00:00 2001 From: "Dhanji R. Prasanna" Date: Mon, 12 Jan 2026 20:44:21 +0530 Subject: [PATCH] docs: Fix documentation inaccuracies and add missing tool documentation Agent: lamport Changes: - docs/architecture.md: Replace non-existent g3-console with studio crate, remove references to non-existent retro_tui.rs, update g3-cli module list to reflect actual source files, fix execution modes list - docs/tools.md: Add missing Research & Memory Tools section documenting research, remember, and rehydrate tools with examples and notes - AGENTS.md: Fix error logs path from logs/errors/ to .g3/errors/ - README.md: Remove references to non-existent CONTRIBUTING.md and LICENSE All documentation links verified working. --- AGENTS.md | 2 +- README.md | 6 +---- docs/architecture.md | 39 +++++++++++++++------------- docs/tools.md | 62 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 85 insertions(+), 24 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0a5ce05..30f98ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -41,7 +41,7 @@ ### For Debugging 1. Session logs: `.g3/sessions//session.json` -2. Error logs: `logs/errors/` +2. Error logs: `.g3/errors/` 3. Context state: Use `/stats` command in interactive mode ## Dangerous/Subtle Code Paths diff --git a/README.md b/README.md index b7bdac6..68b1fb7 100644 --- a/README.md +++ b/README.md @@ -346,8 +346,4 @@ Additional resources: ## License -MIT License - see LICENSE file for details - -## Contributing - -G3 is an open-source project. Contributions are welcome! Please see CONTRIBUTING.md for guidelines. +MIT License diff --git a/docs/architecture.md b/docs/architecture.md index 2c7faa8..c793d4b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -17,7 +17,7 @@ G3 follows a **tool-first philosophy**: instead of just providing advice, it act │ │ │ │ │ │ │ • CLI parsing │◄──►│ • Agent engine │◄──►│ • Anthropic │ │ • Interactive │ │ • Context mgmt │ │ • Databricks │ -│ • Retro TUI │ │ • Tool system │ │ • OpenAI │ +│ • Streaming MD │ │ • Tool system │ │ • OpenAI │ │ • Autonomous │ │ • Streaming │ │ • Embedded │ │ mode │ │ • Task exec │ │ (llama.cpp) │ │ │ │ • TODO mgmt │ │ • OAuth flow │ @@ -50,10 +50,10 @@ G3 follows a **tool-first philosophy**: instead of just providing advice, it act │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ g3-ensembles │ │ g3-console │ -│ │ │ │ -│ • Flock mode │ │ • Web console │ -│ • Multi-agent │ │ • Process mgmt │ -│ • Parallel dev │ │ • Log viewing │ +│ │ │ studio │ +│ • Flock mode │ │ │ +│ • Multi-agent │ │ • Worktree mgmt │ +│ • Parallel dev │ │ • Session mgmt │ └─────────────────┘ └─────────────────┘ ``` @@ -73,7 +73,7 @@ g3/ │ ├── g3-computer-control/ # Computer automation │ ├── g3-planner/ # Planning mode workflow │ ├── g3-ensembles/ # Multi-agent (flock) mode -│ └── g3-console/ # Web monitoring console +│ └── studio/ # Multi-agent workspace manager ├── agents/ # Agent persona definitions ├── logs/ # Session logs (auto-created) └── g3-plan/ # Planning artifacts @@ -138,11 +138,14 @@ pub trait LLMProvider: Send + Sync { **Purpose**: Command-line interface, TUI, and execution modes Key modules: -- `lib.rs` - Main CLI logic and execution modes (~112k chars) -- `retro_tui.rs` - Full-screen retro terminal UI (~63k chars) +- `lib.rs` - Main CLI entry point and mode dispatch +- `interactive.rs` - Interactive REPL mode +- `autonomous.rs` - Autonomous coach-player mode +- `accumulative.rs` - Accumulative autonomous mode +- `agent_mode.rs` - Specialized agent execution - `filter_json.rs` - JSON tool call filtering for display - `ui_writer_impl.rs` - Console output implementation -- `theme.rs` - Color themes for retro mode +- `streaming_markdown.rs` - Real-time markdown formatting **Execution modes**: 1. **Single-shot**: `g3 "task description"` - Execute one task and exit @@ -150,7 +153,7 @@ Key modules: 3. **Autonomous**: `g3 --autonomous` - Coach-player feedback loop 4. **Accumulative**: Default interactive mode with autonomous runs 5. **Planning**: `g3 --planning` - Requirements-driven development -6. **Retro TUI**: `g3 --retro` - Full-screen terminal interface +6. **Agent Mode**: `g3 --agent ` - Run specialized agent personas ### g3-config (Configuration) @@ -229,16 +232,17 @@ Key modules: Flock mode enables parallel development by spawning multiple agent instances working on different parts of a project. -### g3-console (Web Console) +### studio (Multi-Agent Workspace Manager) -**Location**: `crates/g3-console/` -**Purpose**: Web-based monitoring and control +**Location**: `crates/studio/` +**Purpose**: Manage multiple G3 agent sessions using git worktrees Key modules: -- `main.rs` - Axum web server -- `api/` - REST API endpoints -- `process/` - Process detection and control -- `logs.rs` - Log parsing and streaming +- `main.rs` - CLI commands (run, exec, list, status, accept, discard) +- `git.rs` - Git worktree management +- `session.rs` - Session metadata and status tracking + +Studio enables isolated agent sessions by creating git worktrees, allowing multiple agents to work on the same codebase without conflicts. ## Data Flow @@ -359,4 +363,3 @@ Key external dependencies: - **tree-sitter**: Syntax-aware code search - **llama_cpp**: Local model inference (with Metal acceleration) - **fantoccini**: WebDriver client -- **axum**: Web framework (for g3-console) diff --git a/docs/tools.md b/docs/tools.md index 0386186..0643f48 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -15,6 +15,7 @@ This document describes all tools available to the G3 agent. Tools are the prima | **Images** | read_image, take_screenshot | Always | | **Task Management** | todo_read, todo_write | Always | | **Code Intelligence** | code_search, code_coverage | Always | +| **Research & Memory** | research, remember, rehydrate | Always (rehydrate requires `--acd`) | | **WebDriver** | webdriver_* (12 tools) | `--webdriver` or `--chrome-headless` | | **Computer Control** | mouse_click, type_text, find_element, list_windows | `computer_control.enabled = true` | @@ -268,6 +269,67 @@ Generate code coverage report using cargo llvm-cov. --- +## Research & Memory Tools + +### research + +Perform web-based research on a topic. + +**Parameters**: +- `query` (string, required): The research question or topic to investigate + +**Example**: +```json +{"tool": "research", "args": {"query": "Best practices for Rust error handling"}} +``` + +**Notes**: +- Spawns a specialized research agent that browses the web +- Returns a structured research brief with options, trade-offs, and recommendations +- Use for researching APIs, SDKs, libraries, bugs, documentation, etc. + +--- + +### remember + +Save discoveries to project memory. + +**Parameters**: +- `notes` (string, required): Markdown-formatted notes to add to memory + +**Example**: +```json +{"tool": "remember", "args": {"notes": "### Feature Name\n- `file/path.rs` [start..end] - `function_name()`, `StructName`"}} +``` + +**Notes**: +- Memory is stored at `analysis/memory.md` (version controlled) +- New notes are merged with existing memory +- Use to record discovered code locations, patterns, and entry points +- Memory is automatically loaded at agent startup + +--- + +### rehydrate + +Restore dehydrated conversation history from a previous context segment. + +**Parameters**: +- `fragment_id` (string, required): The fragment ID to restore + +**Example**: +```json +{"tool": "rehydrate", "args": {"fragment_id": "abc123"}} +``` + +**Notes**: +- Used with ACD (Aggressive Context Dehydration) feature +- Fragments are stored in `.g3/sessions//fragments/` +- Restores full conversation details from a DEHYDRATED CONTEXT stub +- Enable ACD with `--acd` flag + +--- + ## WebDriver Tools Enabled with `--webdriver` (Safari) or `--chrome-headless` (Chrome).