AI Code Agent

A lightweight, Node.js-based AI agent for code generation and project management, similar to Aider. It integrates with Git, supports a CLI with autocompletion, a rich web UI with visual commands, and fully configurable LLM prompts stored in separate .txt files. Every code change is automatically committed with the prompt included, with support for managing context, undoing changes, running tests, and copying context to the clipboard.

Features

CLI Interface: Interactive terminal with @ file autocompletion, / commands, ! or /run for shell commands, and ? for questions.
Web UI: Browser-based interface with visual buttons for all slash commands, input fields, diffs, commit history, and context management.
Git Integration: Automatically commits code changes with prompts included; supports /undo for reverting.
LLM-Powered: Uses an LLM (e.g., xAI's Grok API) to generate code and answers, with dynamic file context via /add and /drop.
Test & Fix: Runs test scripts and auto-fixes issues within a configurable hop/$ budget.
Configurable Prompts: Customize prompts via separate .txt files in a prompt directory (default: prompts/).
Context Management: Add, remove, or copy files in the LLM context with /add, /drop, and /copy-context.
Minimal Dependencies: Built with Node.js core modules and lightweight libraries (ws for WebSocket, optional clipboardy for CLI clipboard).

Installation

Prerequisites

Node.js (v16 or higher)
Git
An LLM API key (e.g., xAI Grok API, see xAI API)
Optional: xclip (Linux), pbcopy (macOS), or clip (Windows) for CLI clipboard support, or install clipboardy (npm install clipboardy)

Steps

Clone the repository:

git clone https://github.com/your-repo/ai-code-agent.git
cd ai-code-agent

Install dependencies:
```
npm install
```
Only ws (for WebSocket) is required; clipboardy is optional for CLI clipboard support.

Set up environment variables: Create a .env file:

LLM_API_KEY=your-api-key-here
PROMPT_DIR=prompts  # Optional: specify custom prompt directory

Set up prompt files: Create a prompts/ directory with .txt files:
- code_change.txt: For code generation.
- question.txt: For ? or /ask queries.
- fix_error.txt: For test failure fixes. Example code_change.txt:
```
Generate code for {request} in {file}. Include context from {context_files}. Follow project style.
```

Start the agent:

node index.js --prompt-dir custom_prompts  # Optional: override prompt directory

CLI starts immediately.
Web UI is available at http://localhost:3000.

Usage

CLI Commands

Code Changes: Mention files with @ (e.g., Add a function to @main.js to log 'Hello').
- Autocompletes file names (press Tab).
- Changes are applied, committed with the prompt from code_change.txt, and tested (if configured).
Shell Commands: Prefix with ! or /run (e.g., !ls or /run ls to list files).
Questions: Prefix with ? (e.g., ?What is Node.js?) for non-committed answers using question.txt.
Special Commands:
- /undo: Revert the last commit and update context if needed.
- /ask <question>: Same as ? but explicit.
- /add <file>: Add a file to the LLM context (e.g., /add src/main.js).
- /drop <file>: Remove a file from the context (e.g., /drop src/main.js).
- /drop all: Clear all context files.
- /context: Display the current context files.
- /copy-context: Copy the current context (e.g., src/main.js, src/utils.js) to the clipboard.
- /run <command>: Alias for ! to run shell commands.
- /help: List available commands.

Web UI

Access at http://localhost:3000.
Command Toolbar: Click buttons for slash commands (e.g., “Undo”, “Add File”, “Copy Context”) or use the text input for full command syntax.
Input Fields: Commands like /add or /run provide file pickers or text fields.
Context Panel: Shows current context files, updated after /add, /drop, or /copy-context.
Prompt Viewer: View or download prompt files (e.g., code_change.txt) in a settings panel.
Visual Feedback: View file diffs, commit history, test results, and clipboard confirmations in real-time.

Examples

Add a function:
```
Add a function to @main.js to log 'Hello, World!'
```
- Agent reads main.js, context files, and code_change.txt, generates code, commits with the prompt, and runs tests.
- Commit message: AI-generated change: Add a function to @main.js to log 'Hello, World!' Prompt: Generate code for "Add a function to log 'Hello, World!'" in src/main.js. Include context from src/utils.js.
- Web UI: Click “Add File” to select main.js, enter the request, and view the diff.
Ask a question:
```
?What is the event loop in Node.js?
```
- Uses question.txt to generate an answer without modifying files.
- Web UI: Click “Ask” button and enter the question.
Run a shell command:
```
/run npm test
```
- Executes npm test and shows output.
- Web UI: Click “Run” button and enter npm test.
Manage context:
```
/add src/utils.js
/context
/copy-context
/drop src/main.js
```
- Adds src/utils.js, shows [src/utils.js, src/main.js], copies to clipboard, then removes src/main.js.
- Web UI: Click “Add File” to select src/utils.js, “Copy Context” to copy, and “Drop File” to remove src/main.js.
Undo a change:
```
/undo
```
- Reverts the last commit and updates context if needed.
- Web UI: Click “Undo” button.

Configuration

Customize the agent via two files in the project root:

agent-config.json: Configures agent behavior. Example:
```
{
  "promptDir": "prompts",
  "testCommand": "npm test",
  "maxHops": 5,
  "maxBudget": 0.50,
  "retryAttempts": 3
}
```
- promptDir: Directory for prompt .txt files (default: prompts/).
- testCommand: Shell command to run tests.
- maxHops: Max test-and-fix attempts per change.
- maxBudget: Max $ cost for LLM API calls per change (if supported by API).
- retryAttempts: Max retries for failed operations.
Prompt Files (e.g., prompts/code_change.txt): Each prompt type is stored in a separate .txt file in promptDir. Supported files:
- code_change.txt: For code generation (e.g., “Generate code for {request} in {file}.”).
- question.txt: For questions (e.g., “Answer: {question}”).
- fix_error.txt: For test fixes (e.g., “Fix this error in {file}: {error}”).
- Placeholders: {request}, {file}, {context_files}, {error} are replaced dynamically.
- Specify a custom directory in agent-config.json, via --prompt-dir <dir>, or PROMPT_DIR env variable.
- Default prompts are used if files are missing.
context.json: Tracks files in the LLM context. Example:
```
{
  "files": ["src/main.js", "src/utils.js"]
}
```
- Updated by /add and /drop. Check into Git for team sharing.

How It Works

Input: Enter a command in the CLI or web UI (via text or buttons).
Processing:
- For code changes, the agent reads specified files (via @ or /add) and uses grep for context if requested by the LLM.
- The LLM generates code or answers using the prompt from the relevant .txt file in promptDir.
Git: Code changes are applied and committed with the user prompt and content of the .txt file.
Testing: If configured, runs testCommand and auto-fixes failures (up to maxHops or maxBudget) using fix_error.txt.
Context: Managed via /add, /drop, and /copy-context, persisted in context.json.
Output: Results are shown in the CLI or web UI, with diffs, commit details, context, and clipboard confirmations.

Notes

Clipboard Support: CLI uses clipboardy (if installed) or platform-specific commands (pbcopy, xclip, clip). Web UI uses navigator.clipboard (requires localhost or HTTPS).
Security: Shell commands (!, /run) are sanitized. File paths in /add and promptDir are validated.
Context Limits: Max 10 context files to manage LLM token usage. Warns if exceeded.
Prompts in Commits: Prompt file contents are included in commit messages, truncated if too long.
API Costs: For xAI API details, visit xAI API. Tracks usage against maxBudget if supported.
Team Collaboration: Share context.json and promptDir files via Git. Use /copy-context to share context easily.

Contributing

Report issues or suggest features on the GitHub repository.
To add new / commands, edit src/commands.js and add a new .txt file in promptDir.

License

MIT License. See LICENSE for details.

vgrichina/README.md