ros/autocoder
1
0
Fork 0
mirror of https://github.com/leonvanzyl/autocoder.git synced 2026-02-05 08:23:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add npm global package for one-command install

Browse Source 
Add a Node.js CLI wrapper that allows installing AutoForge globally via
`npm install -g autoforge-ai` and running it with a single `autoforge`
command. The CLI handles Python detection, venv management, config
loading, and uvicorn server lifecycle automatically.

New files:
- package.json: npm package config with bin entry, files whitelist,
  and prepublishOnly script that builds the UI
- bin/autoforge.js: thin entry point that imports lib/cli.js
- lib/cli.js: main CLI module (~790 lines) with cross-platform Python
  3.11+ detection, composite venv marker for smart invalidation
  (requirements hash + Python version + path), .env config management
  at ~/.autoforge/.env, server startup with PID file and port detection,
  and signal handling with process tree cleanup
- requirements-prod.txt: runtime-only deps (excludes ruff, mypy, pytest)
- .npmignore: excludes dev files, tests, __pycache__, UI source

Modified files:
- ui/package.json: rename to autoforge-ui to avoid confusion with root
- .gitignore: add *.tgz for npm pack output
- README.md: add npm install as primary quick start method, document
  CLI commands, add Ollama/Vertex AI config sections, new troubleshooting
  entries for Python/venv issues
- GettingStarted.tsx: add Installation, Quick Start, and CLI Commands
  sections to in-app documentation with command reference table
- docsData.ts: add installation and cli-commands sidebar entries

Published as autoforge-ai@0.1.0 on npm.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Auto
2026-02-04 14:48:00 +02:00
parent 451a5a9d05
commit 4549840330
11 changed files with 1193 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

186
README.md
View File

@@ -14,9 +14,11 @@ A long-running autonomous coding agent powered by the Claude Agent SDK. This too
## Prerequisites
### Claude Code CLI (Required)
- **Node.js 20+** - Required for the CLI
- **Python 3.11+** - Auto-detected on first run ([download](https://www.python.org/downloads/))
- **Claude Code CLI** - Install and authenticate (see below)
This project requires the Claude Code CLI to be installed. Install it using one of these methods:
### Claude Code CLI (Required)
**macOS / Linux:**
```bash
@@ -39,35 +41,63 @@ You need one of the following:
## Quick Start
### Option 1: Web UI (Recommended)
### Option 1: npm Install (Recommended)
**Windows:**
```cmd
start_ui.bat
```
**macOS / Linux:**
```bash
./start_ui.sh
npm install -g autoforge-ai
autoforge
```
On first run, AutoForge automatically:
1. Checks for Python 3.11+
2. Creates a virtual environment at `~/.autoforge/venv/`
3. Installs Python dependencies
4. Copies a default config file to `~/.autoforge/.env`
5. Starts the server and opens your browser
### CLI Commands
```
autoforge Start the server (default)
autoforge config Open ~/.autoforge/.env in $EDITOR
autoforge config --path Print config file path
autoforge config --show Show active configuration values
autoforge --port PORT Custom port (default: auto from 8888)
autoforge --host HOST Custom host (default: 127.0.0.1)
autoforge --no-browser Don't auto-open browser
autoforge --repair Delete and recreate virtual environment
autoforge --version Print version
autoforge --help Show help
```
### Option 2: From Source (Development)
Clone the repository and use the start scripts directly. This is the recommended path if you want to contribute or modify AutoForge itself.
```bash
git clone https://github.com/leonvanzyl/autoforge.git
cd autoforge
```
**Web UI:**
| Platform | Command |
|---|---|
| Windows | `start_ui.bat` |
| macOS / Linux | `./start_ui.sh` |
This launches the React-based web UI at `http://localhost:5173` with:
- Project selection and creation
- Kanban board view of features
- Real-time agent output streaming
- Start/pause/stop controls
### Option 2: CLI Mode
**CLI Mode:**
**Windows:**
```cmd
start.bat
```
**macOS / Linux:**
```bash
./start.sh
```
| Platform | Command |
|---|---|
| Windows | `start.bat` |
| macOS / Linux | `./start.sh` |
The start script will:
1. Check if Claude CLI is installed
@@ -130,44 +160,43 @@ Features are stored in SQLite via SQLAlchemy and managed through an MCP server t
## Project Structure
```
autonomous-coding/
├── start.bat # Windows CLI start script
├── start.sh # macOS/Linux CLI start script
├── start_ui.bat # Windows Web UI start script
├── start_ui.sh # macOS/Linux Web UI start script
├── start.py # CLI menu and project management
├── start_ui.py # Web UI backend (FastAPI server launcher)
├── autonomous_agent_demo.py # Agent entry point
├── agent.py # Agent session logic
├── client.py # Claude SDK client configuration
├── security.py # Bash command allowlist and validation
├── progress.py # Progress tracking utilities
├── prompts.py # Prompt loading utilities
autoforge/
├── bin/ # npm CLI entry point
├── lib/ # CLI bootstrap and setup logic
├── start.py # CLI menu and project management
├── start_ui.py # Web UI backend (FastAPI server launcher)
├── autonomous_agent_demo.py # Agent entry point
├── agent.py # Agent session logic
├── client.py # Claude SDK client configuration
├── security.py # Bash command allowlist and validation
├── progress.py # Progress tracking utilities
├── prompts.py # Prompt loading utilities
├── api/
│ └── database.py # SQLAlchemy models (Feature table)
│ └── database.py # SQLAlchemy models (Feature table)
├── mcp_server/
│ └── feature_mcp.py # MCP server for feature management tools
│ └── feature_mcp.py # MCP server for feature management tools
├── server/
│ ├── main.py # FastAPI REST API server
│ ├── websocket.py # WebSocket handler for real-time updates
│ ├── schemas.py # Pydantic schemas
│ ├── routers/ # API route handlers
│ └── services/ # Business logic services
├── ui/ # React frontend
│ ├── main.py # FastAPI REST API server
│ ├── websocket.py # WebSocket handler for real-time updates
│ ├── schemas.py # Pydantic schemas
│ ├── routers/ # API route handlers
│ └── services/ # Business logic services
├── ui/ # React frontend
│ ├── src/
│ │ ├── App.tsx # Main app component
│ │ ├── hooks/ # React Query and WebSocket hooks
│ │ └── lib/ # API client and types
│ │ ├── App.tsx # Main app component
│ │ ├── hooks/ # React Query and WebSocket hooks
│ │ └── lib/ # API client and types
│ ├── package.json
│ └── vite.config.ts
├── .claude/
│ ├── commands/
│ │ └── create-spec.md # /create-spec slash command
│ ├── skills/ # Claude Code skills
│ └── templates/ # Prompt templates
├── generations/ # Generated projects go here
├── requirements.txt # Python dependencies
└── .env # Optional configuration (N8N webhook)
│ │ └── create-spec.md # /create-spec slash command
│ ├── skills/ # Claude Code skills
│ └── templates/ # Prompt templates
├── requirements.txt # Python dependencies (development)
├── requirements-prod.txt # Python dependencies (npm install)
├── package.json # npm package definition
└── .env # Optional configuration
```
---
@@ -264,11 +293,20 @@ The UI receives live updates via WebSocket (`/ws/projects/{project_name}`):
---
## Configuration (Optional)
## Configuration
AutoForge reads configuration from a `.env` file. The file location depends on how you installed AutoForge:
| Install method | Config file location | Edit command |
|---|---|---|
| npm (global) | `~/.autoforge/.env` | `autoforge config` |
| From source | `.env` in the project root | Edit directly |
A default config file is created automatically on first run. Use `autoforge config` to open it in your editor, or `autoforge config --show` to print the active values.
### N8N Webhook Integration
The agent can send progress notifications to an N8N webhook. Create a `.env` file:
Add to your `.env` to send progress notifications to an N8N webhook:
```bash
# Optional: N8N webhook for progress notifications
@@ -290,7 +328,7 @@ When test progress increases, the agent sends:
### Using GLM Models (Alternative to Claude)
To use Zhipu AI's GLM models instead of Claude, add these variables to your `.env` file in the AutoForge directory:
Add these variables to your `.env` file to use Zhipu AI's GLM models:
```bash
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic
@@ -305,6 +343,36 @@ This routes AutoForge's API requests through Zhipu's Claude-compatible API, allo
Get an API key at: https://z.ai/subscribe
### Using Ollama Local Models
Add these variables to your `.env` file to run agents with local models via Ollama v0.14.0+:
```bash
ANTHROPIC_BASE_URL=http://localhost:11434
ANTHROPIC_AUTH_TOKEN=ollama
API_TIMEOUT_MS=3000000
ANTHROPIC_DEFAULT_SONNET_MODEL=qwen3-coder
ANTHROPIC_DEFAULT_OPUS_MODEL=qwen3-coder
ANTHROPIC_DEFAULT_HAIKU_MODEL=qwen3-coder
```
See the [CLAUDE.md](CLAUDE.md) for recommended models and known limitations.
### Using Vertex AI
Add these variables to your `.env` file to run agents via Google Cloud Vertex AI:
```bash
CLAUDE_CODE_USE_VERTEX=1
CLOUD_ML_REGION=us-east5
ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-5@20251101
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-5@20250929
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-3-5-haiku@20241022
```
Requires `gcloud auth application-default login` first. Note the `@` separator (not `-`) in Vertex AI model names.
---
## Customization
@@ -335,6 +403,18 @@ This is normal. The initializer agent is generating detailed test cases, which t
**"Command blocked by security hook"**
The agent tried to run a command not in the allowlist. This is the security system working as intended. If needed, add the command to `ALLOWED_COMMANDS` in `security.py`.
**"Python 3.11+ required but not found"**
Install Python 3.11 or later from [python.org](https://www.python.org/downloads/). Make sure `python3` (or `python` on Windows) is on your PATH.
**"Python venv module not available"**
On Debian/Ubuntu, the venv module is packaged separately. Install it with `sudo apt install python3.XX-venv` (replace `XX` with your Python minor version, e.g., `python3.12-venv`).
**"AutoForge is already running"**
A server instance is already active. Use the browser URL shown in the terminal, or stop the existing instance with Ctrl+C first.
**Virtual environment issues after a Python upgrade**
Run `autoforge --repair` to delete and recreate the virtual environment from scratch.
---
## License