Skip to content

Commit db16739

Browse files
author
Tarik Moustaid
committed
Refactor: Complete overhaul of README.md to reflect G-Coder's new capabilities and branding.
- Major structural update to README.md: Added detailed feature list (ADK, Multi-LLM, LSP), installation guide, usage examples, roadmap, and project structure. - Dependencies: Added 'playwright' to pyproject.toml to enable browser interaction tools. - Fix: Corrected logic in file_tools.edit_file to correctly handle newline termination when inserting content, ensuring line integrity during edits. - Untracked: Added LICENSE file (content not verified in this commit set).
1 parent f4175da commit db16739

4 files changed

Lines changed: 185 additions & 59 deletions

File tree

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 GreazySpoon (Tarik Moustaid)
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 157 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,185 @@
1-
# GCoder Project: Autonomous AI Agent Framework
21

3-
This repository hosts an advanced, modular AI agent framework designed for complex system interaction, development assistance, and automated task execution. The core operational paradigm strictly adheres to the **Observe -> Orient -> Decide -> Act -> Verify** lifecycle.
2+
# G-Coder: AI Agent for Code & System Tasks
43

5-
![General Agent Interface](screenshots/screen1.png)
4+
<div align="center">
5+
6+
```
7+
██████╗ ██████╗ ██████╗ ██████╗ ███████╗██████╗
8+
██╔════╝ ██╔═══██╗██╔══██╗██╔══██╗██╔════╝██╔══██╗
9+
██║ ███╗██║ ██║██║ ██║██║ ██║█████╗ ██████╔╝
10+
██║ ██║██║ ██║██║ ██║██║ ██║██╔══╝ ██╔══██╗
11+
╚██████╔╝╚██████╔╝██████╔╝██████╔╝███████╗██║ ██║
12+
╚═════╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝ ╚═╝
13+
```
14+
**An AI agent CLI for system admin and code dev tasks, powered by the Google Agent Development Kit.**
15+
16+
</div>
17+
18+
![G-Coder Hero Image](./screenshots/screen1.png)
19+
20+
21+
**G-Coder** is a sophisticated, command-line AI agent designed to be your partner in software development, DevOps, and system administration. Built on the powerful and fluid [Google Agent Development Kit (ADK)](https://google.github.io/adk-docs/), G-Coder is engineered for speed, reliability, and effectiveness.
22+
23+
Its core philosophy revolves around providing the AI with meticulously designed tools, intuitive naming conventions, and a smart system prompt. This combination makes the agent remarkably effective, even with smaller open-source models, and an absolute powerhouse with frontier models, capable of conducting highly complex tasks.
624

725
---
8-
**Note:** The screenshot above illustrates the typical interactive environment or interface of the running agent.
26+
27+
## ✨ Features
28+
29+
* **Powered by Google ADK**: Leverages the speed, reliability, and fluidity of the Google Agent Development Kit for a robust and responsive agentic experience.
30+
* **Multi-LLM Backend**: Seamlessly switch between different LLM providers.
31+
* ✅ **Ollama** (for local models)
32+
* ✅ **OpenAI**
33+
* ✅ **Gemini AI Studio**
34+
* ✅ **vLLM** (or any OpenAI-compatible endpoint)
35+
* **🧠 Code Intelligence Toolbox (LSP-Powered)**: This is G-Coder's most powerful feature. It indexes your codebase and uses the Language Server Protocol (LSP) to provide the agent with deep, contextual understanding of your code. This allows it to navigate complex projects, find definitions, and trace references with surgical precision, all without consuming excessive context.
36+
* **🤖 Autonomous Task Mode**: For complex, multi-step tasks, you can delegate control to the agent using the `@task` command. It will work autonomously towards the goal, providing a live-updating dashboard of its progress. (Note: This feature is experimental as we continue to refine multiple autonomous agent patterns).
37+
* **🛠️ Comprehensive Toolset**:
38+
* **File Operations**: Read, write, and make surgical edits to files.
39+
* **Shell Execution**: Cross-platform support for running terminal commands.
40+
* **Service Management**: Start, monitor, and stop long-running services like web servers and dev watchers.
41+
* **Vision Tools** (Optional): Enable vision capabilities for multimodal models to analyze images.
42+
* **Browser Tools** (Optional): Allow the agent to interact with web pages, interpret UIs, and perform actions in a browser.
43+
* **💡 Flexible Interaction Modes**:
44+
* **Interactive Mode**: A rich, conversational CLI for back-and-forth collaboration.
45+
* **Command-Line Mode**: Execute single, automated tasks and exit, perfect for scripting.
46+
* **🚀 REST API Server**: Start G-Coder with a FastAPI backend, exposing its capabilities via a REST API with a built-in Swagger UI. This is perfect for serving agent environments in Docker containers.
47+
* **🎨 Dynamic UI**: A visually pleasing and informative terminal interface that shows a new vaporwave-style logo banner on each startup.
48+
949
---
1050

11-
## 1. Project Architecture Overview
51+
## 🚀 Installation & Setup
1252

13-
The framework is organized into functional layers for clarity and extensibility:
53+
### Prerequisites
54+
* Python 3.9+
55+
* Git
1456

15-
| Path | Description | Key Files |
16-
| :--- | :--- | :--- |
17-
| **`src/gcoder/`** | Core Python logic and agent definition. | `main.py` (Entry Point) |
18-
| **`src/gcoder/agents/`** | Implementations of the AI decision-makers. | `basic_agent.py`, `autonomous_agent.py` |
19-
| **`src/gcoder/tools/`** | The comprehensive toolkit providing capabilities to the agents. | `execution_tools.py`, `file_tools.py`, `code_tools.py`, `vision_tools.py` |
20-
| **`src/gcoder/prompts/`** | Stores system instructions and persona definitions. | `basic_agent_instruction.txt` |
21-
| **`src/gcoder/lsp/`** | Integration layer for Language Server Protocol diagnostics. | `lsp_manager.py` |
22-
| **`screenshots/`** | Visual documentation references. | `screen1.png`, `screen2.png` |
57+
### 1. Clone the Repository
58+
```bash
59+
git clone https://github.com/GreazySpoon/gcoder.git
60+
cd gcoder
61+
```
2362

24-
## 2. Setup and Installation
63+
### 2. Install Dependencies
64+
It is highly recommended to use a virtual environment.
65+
```bash
66+
python -m venv .venv
67+
source .venv/bin/activate # On Windows, use `.venv\Scripts\activate`
68+
pip install -e .
69+
```
70+
This installs the project in "editable" mode, so changes you make to the source code are immediately reflected.
2571

26-
### Prerequisites
72+
### 3. Configure Your LLM
73+
The first time you run `gcoder`, it will create a configuration file at `~/.gcoder/config.ini`. Open this file and edit it to select your desired LLM provider and enter your model names.
2774

28-
* Python 3.8+
29-
* Node.js (Likely required due to `package.json` presence)
75+
```ini
76+
[default]
77+
# Supported values: ollama, openai, gemini, vllm
78+
active_provider = ollama
3079

31-
### Installation
80+
[ollama]
81+
host = http://localhost:11434
82+
model = llama3:latest
83+
autonomous_model = llama3:latest
3284

33-
1. **Clone & Navigate:**
34-
```bash
35-
git clone <repository-url>
36-
cd gcoder-project
37-
```
85+
[openai]
86+
# Your OPENAI_API_KEY must be set as an environment variable.
87+
model = gpt-4o
88+
autonomous_model = gpt-4o
89+
```
3890

39-
2. **Install Dependencies:**
40-
The presence of `pyproject.toml` suggests a modern dependency manager like Poetry or PDM.
41-
```bash
42-
# Recommended (if using Poetry)
43-
poetry install
44-
45-
# Fallback if necessary
46-
# pip install -r requirements.txt (if requirements.txt exists)
47-
48-
# Install Node dependencies
49-
npm install
50-
```
91+
### 4. (Recommended) Enable Code Intelligence
92+
To unlock the powerful Code Intelligence tools, you need to install the relevant Language Server Protocol (LSP) servers. The agent will automatically detect them if they are in your system's PATH.
5193

52-
## 3. Execution and Operation
94+
For **Python** support (heavily tested), install `pyright`:
95+
```bash
96+
npm install -g pyright-langserver
97+
```
98+
99+
Support for TypeScript/JavaScript (`typescript-language-server`) and C# (`omnisharp`) is also available.
53100

54-
The application is executed via the main script, which handles argument parsing and initiates the primary agent loop.
101+
---
55102

56-
**Running a Task (from `src/gcoder/main.py`):**
103+
## 💻 How to Use
104+
105+
### Interactive Mode
106+
This is the default mode. Start a rich, conversational session. The `-a` flag enables human approval for sensitive commands like `sudo`.
57107
```bash
58-
python src/gcoder/main.py --task "Analyze the code and update the README"
108+
gcoder -a
59109
```
60110

61-
### Tool Capabilities Summary
111+
### Autonomous Task Mode
112+
Delegate a complex task to the agent within the interactive session using the `@task` keyword.
113+
```
114+
> /path/to/your/project ❯ @task Refactor the database connection logic in `main.py` to use a connection pool.
115+
```
116+
117+
### Single-Shot Task Mode
118+
Run a single autonomous task from your terminal and exit. Useful for scripting.
119+
```bash
120+
gcoder --task "Analyze the `docker-compose.yml` file and explain the services it defines."
121+
```
122+
123+
### API Server Mode
124+
Start the FastAPI server (defaults to port 8844).
125+
```bash
126+
gcoder --api 8844
127+
```
128+
You can now access the Swagger UI at `http://127.0.0.1:8844/docs`.
129+
130+
---
131+
132+
## 🖼️ Usage Examples
133+
134+
#### Interactive Chat & File Editing
135+
![G-Coder Usage Example 1](./screenshots/screen2.png)
62136

63-
Agents operate by leveraging the following tool categories:
64-
* **Execution:** `run_in_terminal` allows safe execution of shell commands (e.g., `ls`, `git`).
65-
* **File System:** Tools for reading, writing, and surgical editing of files (`read_file`, `edit_file`).
66-
* **Code Intelligence:** LSP-backed tools for finding definitions and references across the codebase.
137+
#### Autonomous Task Dashboard
138+
![G-Coder Usage Example 2](./screenshots/screen3.png)
67139

68-
## 4. Usage Example: File Modification Workflow
140+
---
141+
142+
## 🛣️ Roadmap & Future Enhancements
143+
We are constantly working to improve G-Coder. Here's what's on the horizon:
144+
145+
- [ ] **Autonomous Agent**: Enhance the autonomous agent to run reliably until a task is achieved or context limit is reached.
146+
- [ ] **Web UI**: Develop a full-featured web interface for interacting with the agent.
147+
- [ ] **Browser Interaction**: Further improve the reliability and capabilities of the browser tools.
148+
- [ ] **Multi-Code-Project (MCP) Support**: Better management for tasks spanning multiple codebases.
149+
- [ ] **API Endpoints**: Add dedicated API endpoints for browser and agent control.
150+
- [ ] **Session Management**: Persistent and shareable agent sessions.
151+
- [ ] **Background Subtasks**: Ability to spawn and manage background tasks.
152+
- [ ] **Pip Installation**: Make the package easily installable via `pip install gcoder`.
69153

70-
The agent excels at multi-step technical tasks. This secondary screenshot demonstrates a sequence where the agent reads file content and executes an edit based on a user request.
154+
---
71155

72-
![Example Usage Workflow](screenshots/screen2.png)
156+
## 📂 Project Structure
73157

74-
## 5. Known Observations (From Code Inspection)
158+
A brief overview of the project's layout:
75159

76-
* **Agent Configuration:** Agents like `basic_agent.py` have compile-time configuration toggles for enabling advanced features like **Thinking** and **Vision**.
77-
* **External Dependencies:** The `basic_agent.py` shows import errors related to `google.adk.models`, suggesting potential integration with an internal or specific Google SDK that might be missing or misconfigured in the current environment.
160+
```
161+
.
162+
├── src/gcoder/
163+
│ ├── api/ # FastAPI server logic.
164+
│ ├── agents/ # Agent definitions and prompts.
165+
│ ├── system/ # Core system components (tools, callbacks, capabilities).
166+
│ ├── ui/ # Rich UI components like the task dashboard.
167+
│ ├── banners/ # ASCII art banners for the CLI.
168+
│ ├── config.py # Configuration management.
169+
│ ├── main.py # CLI entry point and argument parsing.
170+
│ ├── models.py # LLM model loading and abstraction.
171+
│ └── terminal.py # Main interactive terminal loop and logic.
172+
├── pyproject.toml # Project definition and dependencies.
173+
└── README.md # You are here!
174+
```
175+
176+
---
177+
178+
## 🙌 Contributing
179+
Contributions are welcome! If you'd like to help improve G-Coder, please feel free to fork the repository, create a new branch for your feature or bug fix, and submit a pull request.
180+
181+
---
78182

79-
## 6. Configuration Files
183+
## 📜 License
80184

81-
Initial environment variables and settings should be checked in:
82-
* `example-config.ini`
83-
* `pyproject.toml` (for Python dependencies and metadata)
185+
MIT License

‎pyproject.toml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,8 @@ dependencies = [
2828
"pydantic",
2929
"python-multipart",
3030
"python-dotenv",
31-
"prompt_toolkit"
31+
"prompt_toolkit",
32+
"playwright"
3233
]
3334

3435
[project.urls]

‎src/gcoder/tools/file_tools.py‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -75,9 +75,11 @@ def edit_file(tool_context: ToolContext, path: str, start_line: int, end_line: i
7575
if start_idx > end_idx:
7676
end_idx = start_idx
7777

78-
new_content_lines = new_content.splitlines(True)
79-
if not new_content_lines and new_content:
80-
new_content_lines = [new_content]
78+
# Split the new content into lines, and ensure each line ends with a newline.
79+
if new_content:
80+
new_content_lines = [line + '\n' for line in new_content.splitlines()]
81+
else:
82+
new_content_lines = []
8183

8284
lines[start_idx:end_idx] = new_content_lines
8385

0 commit comments

Comments
 (0)