alexforge 0.2.0__py3-none-any.whl

alexforge-0.2.0.dist-info/METADATA

@@ -0,0 +1,1091 @@
+Metadata-Version: 2.4
+Name: alexforge
+Version: 0.2.0
+Summary: A local-first, repo-aware AI coding agent powered by Ollama
+Home-page: https://github.com/alexforge/localforge.git
+Author: localforge contributors
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: httpx>=0.25
+Requires-Dist: typer>=0.9
+Requires-Dist: pathspec>=0.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: cryptography>=41.0
+Requires-Dist: pyspnego>=0.10
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# AlexForge
+
+**A local-first, repo-aware AI coding agent powered by Ollama.**
+
+AlexForge is a fully offline, privacy-first AI coding agent that lives in your
+terminal. Point it at a codebase, describe a task in plain English, and it will
+analyze the code, build an execution plan, generate patches, run verification,
+and iterate — all using a local LLM through [Ollama](https://ollama.com).
+
+> **Your code never leaves your machine.** No API keys. No cloud. No telemetry.
+
+---
+
+## Why AlexForge?
+
+| Feature | AlexForge | Cloud-based agents |
+|---------|------------|--------------------|
+| **Privacy** | 100 % local — code never leaves your machine | Code sent to external servers |
+| **Cost** | Free forever (runs on your hardware) | Per-token billing |
+| **Internet** | Works fully offline | Requires internet connection |
+| **Repo awareness** | SQLite-indexed codebase with FTS5 search | Context window stuffing |
+| **Safety** | Diff preview + confirmation + backups + rollback | Varies |
+| **Transparency** | Open source, inspectable agent prompts | Black box |
+
+### What makes it stand out
+
+- **Tool-use from chat.** The LLM can autonomously read files, write code,
+  edit files, run shell commands, and search the codebase — all from within
+  the interactive chat. No more copy-pasting suggestions; the agent acts
+  directly on your code, similar to Claude Code.
+- **Multi-agent architecture.** Six specialist agents (Analyzer → Planner →
+  Coder → Verifier → Reflector → Summarizer) collaborate through structured
+  JSON handoffs, each with its own system prompt and output schema. This
+  separation of concerns produces more reliable results than single-prompt
+  approaches.
+- **Interactive chat.** `alexforge chat` gives you a conversational REPL —
+  ask questions about your codebase, explore code, and plan changes
+  interactively. Chat history persists between sessions. Built-in slash
+  commands: `/run`, `/read`, `/context`, `/tokens`, and more.
+- **Streaming output.** See model responses as they generate, token by token.
+  No more staring at a spinner — watch the agent think in real time.
+- **Git integration.** Automatic git checkpoints before and after autofix runs.
+  Track changes with your existing git workflow alongside file-based backups.
+- **Auto-detect context window.** Queries the Ollama API to determine your
+  model's actual context window size — no manual configuration needed.
+- **Token-budget-aware.** A dedicated context assembler and token budget manager
+  keep every prompt within the model's context window — no silent truncation
+  surprises.
+- **Smart retrieval.** Combines FTS5 full-text search, filename fuzzy matching,
+  symbol search, and optional ripgrep integration. Chunks are ranked by
+  term-frequency, path relevance, recency, and deduplicated automatically.
+- **Multi-language indexing.** Enhanced symbol extraction for Python, JavaScript,
+  TypeScript, Go, Rust, Java, C#, Ruby, PHP, C/C++, and more — including
+  interfaces, types, enums, constants, async functions, and module exports.
+- **Safe by default.** Every patch is shown as a diff, backed up before
+  application, validated for syntax and safety, and only written after explicit
+  approval (or `--yes`). Rollback is always one command away. Destructive
+  shell commands are blocked for safety.
+- **Project rules.** Add conventions to `.localforge/rules.md` and they're
+  injected into every agent prompt — the agent follows your coding standards.
+
+---
+
+## Table of Contents
+
+1. [Requirements](#requirements)
+2. [Installation](#installation)
+3. [Quick Start](#quick-start)
+4. [Complete CLI Reference](#complete-cli-reference)
+5. [Architecture](#architecture)
+6. [Agent Loop](#agent-loop)
+7. [How Retrieval Works](#how-retrieval-works)
+8. [Project Rules](#project-rules)
+9. [Configuration Reference](#configuration-reference)
+10. [Model Recommendations](#model-recommendations)
+11. [Choosing and Switching Models](#choosing-and-switching-models)
+12. [Workflow Examples](#workflow-examples)
+13. [Safety & Backups](#safety--backups)
+14. [Tips for Best Results](#tips-for-best-results)
+15. [Limitations](#limitations)
+16. [Comparison with Cloud Agents](#comparison-with-cloud-agents)
+17. [Changelog](#changelog)
+18. [Contributing](#contributing)
+19. [License](#license)
+
+---
+
+## Requirements
+
+| Dependency | Version | Notes |
+|------------|---------|-------|
+| Python | **3.11 +** | 3.12 and 3.13 work too |
+| [Ollama](https://ollama.com) | latest | Must be running (`ollama serve`) |
+| ripgrep (`rg`) | *optional* | Speeds up file discovery if installed |
+| Git | *optional* | Used for change tracking |
+
+### Hardware recommendations
+
+| Setup | VRAM | Recommended model | Profile |
+|-------|------|-------------------|---------|
+| Minimum | 4–6 GB | `qwen2.5-coder:7b` | `small` |
+| Recommended | 8–16 GB | `qwen2.5-coder:14b` | `medium` |
+| Best results | 24+ GB | `qwen2.5-coder:32b` | `large` |
+
+---
+
+## Installation
+
+### Recommended: pipx (zero-friction, works immediately)
+
+[`pipx`](https://pipx.pypa.io) installs CLI tools in isolated environments and
+automatically wires them into your PATH — no manual setup, works on the first
+try on any machine.
+
+```bash
+# Install pipx (once per machine)
+py -m pip install --user pipx
+py -m pipx ensurepath
+```
+
+Close and reopen your terminal, then:
+
+```bash
+pipx install alexforge
+alexforge --version   # works immediately
+```
+
+> **Windows users:** `pipx ensurepath` handles PATH for you. After running it
+> once, every subsequent `pipx install <tool>` just works.
+
+### Alternative: plain pip
+
+```bash
+pip install alexforge
+```
+
+> **Note:** On Windows, `pip install` may place the `alexforge` command in a
+> Scripts directory that is not yet on your PATH. If `alexforge` is not
+> recognised after install, run the one-time fix below and restart your
+> terminal.
+
+#### Windows PATH fix (one time only)
+
+```powershell
+alexforge setup-shell
+```
+
+If the `alexforge` command is still not available yet, use:
+
+```powershell
+py -m localforge setup-shell
+```
+
+Then **close and reopen your terminal** — `alexforge` will work from that
+point on, permanently.
+
+### From source (development)
+
+```bash
+git clone https://github.com/alexforge/localforge.git
+cd localforge
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+### 1. Start with cloud-chat (fastest path)
+
+If your main workflow is cloud-powered coding assistance, start here first:
+
+```bash
+cd your-project/
+alexforge cloud-chat
+```
+
+What happens on first run:
+- You paste browser auth headers when prompted.
+- AlexForge validates and caches credentials locally.
+- It auto-checks your repo index and creates/refreshes it if needed.
+- You enter an interactive cloud session (Gemini 3.1 Pro preview).
+
+Useful options:
+
+```bash
+alexforge cloud-chat --fresh-auth   # force re-authentication
+alexforge cloud-chat --repo ./myapp # target a specific repo
+```
+
+### 2. Install Ollama and pull a model (for local mode)
+
+```bash
+# Install Ollama from https://ollama.com
+ollama pull qwen2.5-coder:7b
+```
+
+### 3. Initialize your project
+
+```bash
+cd your-project/
+alexforge init
+```
+
+This creates a `.localforge/` directory with:
+- `config.yml` — model and behavior settings
+- `rules.md` — project-specific coding rules (injected into every prompt)
+- `commands.yml` — custom verification commands
+
+### 4. Index the codebase
+
+```bash
+alexforge index
+```
+
+Builds a SQLite index with full-text search, symbol extraction, and file
+metadata. Runs in seconds for most repos. Re-run after major changes.
+
+### 5. Search your code (optional)
+
+```bash
+alexforge search "authentication"
+alexforge search "UserModel" --mode symbol
+alexforge search "config.py" --mode filename
+```
+
+### 6. Run the full autofix pipeline
+
+```bash
+alexforge autofix "fix the authentication bug in the login endpoint"
+```
+
+The agent will: analyze → plan → patch → verify → reflect → iterate. All
+locally, all with your approval at each step.
+
+---
+
+## Complete CLI Reference
+
+### Global Options
+
+```bash
+alexforge --version          # Show version
+alexforge --verbose          # Enable debug logging (aliases: --debug)
+alexforge --help             # Show all commands
+```
+
+### `alexforge cloud-chat`
+
+Start an interactive cloud-powered coding session.
+
+```bash
+alexforge cloud-chat
+alexforge cloud-chat --fresh-auth
+alexforge cloud-chat --repo ./myapp
+```
+
+When to use this:
+- You want fast autonomous assistance with cloud model quality.
+- You are okay using browser-derived auth headers at runtime.
+
+Behavior summary:
+- Prompts for auth headers (or reuses cached ones if still valid).
+- Validates credentials and safely re-prompts on invalid/expired auth.
+- Ensures repo index exists before session starts.
+- Opens an interactive chat loop for coding tasks.
+
+| Flag | Description |
+|------|-------------|
+| `--fresh-auth` | Force re-entering authentication headers |
+| `--repo`, `-r` | Path to the repository root |
+
+### `alexforge init`
+
+Initialize a `.localforge/` directory with default configuration files.
+
+```bash
+alexforge init                 # current directory
+alexforge init /path/to/repo   # specific repo
+```
+
+Creates: `config.yml`, `rules.md`, `commands.yml`.
+
+### `alexforge index`
+
+Build or refresh the SQLite code index for fast retrieval. Does **not** require
+Ollama to be running.
+
+```bash
+alexforge index                # incremental update (only re-indexes changed files)
+alexforge index --force        # full re-index from scratch
+alexforge index --repo ./myapp
+```
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Re-index all files from scratch |
+| `--repo`, `-r` | Path to the repository root (default: `.`) |
+
+### `alexforge search`
+
+Search the codebase index directly — great for exploring what the agent will see.
+
+```bash
+alexforge search "database connection"          # search everything
+alexforge search "UserModel" --mode symbol       # search symbol names only
+alexforge search "config" --mode filename        # search file names only
+alexforge search "authenticate" --mode text      # full-text search only
+alexforge search "login" --limit 20              # more results
+```
+
+| Flag | Description |
+|------|-------------|
+| `--mode`, `-m` | Search mode: `all`, `text`, `filename`, `symbol` |
+| `--limit`, `-n` | Max results (default: `10`) |
+| `--repo`, `-r` | Path to the repository root |
+
+### `alexforge analyze`
+
+Retrieve the most relevant code chunks for a given task description. Useful to
+preview what context the agent will work with.
+
+```bash
+alexforge analyze "why is the login endpoint slow?"
+alexforge analyze "add pagination to the users API" --limit 20
+alexforge analyze "..." --model codellama:13b
+```
+
+| Flag | Description |
+|------|-----------|
+| `--limit`, `-n` | Max chunks to retrieve (default: `10`) |
+| `--model`, `-m` | Override the Ollama model |
+| `--repo`, `-r` | Path to the repository root |
+
+### `alexforge plan`
+
+Run analysis and produce an execution plan, saved to `.localforge/last_plan.json`.
+
+```bash
+alexforge plan "add input validation to the signup form"
+alexforge plan "..." --model qwen2.5-coder:32b
+```
+
+| Flag | Description |
+|------|-----------|
+| `--model`, `-m` | Override the Ollama model |
+| `--repo`, `-r` | Path to the repository root |
+
+### `alexforge patch`
+
+Generate and apply code patches from a saved plan.
+
+```bash
+alexforge patch "add input validation to the signup form"
+alexforge patch "fix bug" --step 2          # execute only step 2
+alexforge patch "fix bug" --dry-run         # preview without writing
+alexforge patch "fix bug" --yes             # auto-approve all patches
+alexforge patch "fix bug" --model codellama:13b
+```
+
+| Flag | Description |
+|------|-----------|
+| `--step`, `-s` | Execute only this step number |
+| `--dry-run` | Show patches without applying |
+| `--yes`, `-y` | Auto-approve all patches |
+| `--model`, `-m` | Override the Ollama model |
+| `--repo`, `-r` | Path to the repository root |
+
+### `alexforge verify`
+
+Run the project's verification suite. Auto-detects: **pytest**, **ruff**,
+**mypy**, **npm test**, **go test**.
+
+```bash
+alexforge verify
+alexforge verify --repo ./myapp
+```
+
+### `alexforge autofix`
+
+**The main command.** Runs the full agent pipeline end-to-end: analyze → plan →
+patch → verify → reflect → iterate.
+
+```bash
+alexforge autofix "fix the failing test in test_users.py"
+alexforge autofix "refactor the database layer to use async" --model codellama:13b
+alexforge autofix "add caching to the API" --yes --profile large
+```
+
+| Flag | Description |
+|------|-------------|
+| `--yes`, `-y` | Auto-approve all patches |
+| `--dry-run` | Show patches without applying them |
+| `--model`, `-m` | Override the Ollama model |
+| `--profile`, `-p` | Model profile: `small`, `medium`, `large` |
+| `--max-iterations` | Override max agent iterations |
+| `--repo`, `-r` | Path to the repository root |
+
+### `alexforge diff`
+
+Show unified diffs for changes made by alexforge (uses the backup system).
+
+```bash
+alexforge diff                       # latest backup
+alexforge diff 20260403_143022       # specific timestamp
+```
+
+### `alexforge rollback`
+
+Undo changes by restoring files from a backup snapshot.
+
+```bash
+alexforge rollback                   # list available backups
+alexforge rollback 20260403T143022   # restore specific backup
+```
+
+### `alexforge status`
+
+Show project status: index stats, Ollama health, model info, git status, and last task.
+
+```bash
+alexforge status
+```
+
+### `alexforge models`
+
+List all available models on your Ollama instance and show the current default.
+
+```bash
+alexforge models
+```
+
+### `alexforge set-model`
+
+Set your default model interactively or by specifying a model name directly.
+
+```bash
+alexforge set-model                    # interactive selection
+alexforge set-model qwen2.5-coder:14b  # set directly
+```
+
+| Flag | Description |
+|------|-------------|
+| `--repo`, `-r` | Path to the repository root |
+
+### `alexforge chat`
+
+Start an interactive **local** conversational REPL (Ollama) about your codebase.
+Ask questions, explore code, and plan changes interactively. Chat history
+persists between sessions.
+
+```bash
+alexforge chat
+alexforge chat --model codellama:13b
+```
+
+| Flag | Description |
+|------|-------------|
+| `--model`, `-m` | Override the Ollama model |
+| `--repo`, `-r` | Path to the repository root |
+
+**In-chat commands:**
+
+| Command | Description |
+|---------|-------------|
+| `/clear` | Clear chat history |
+| `/context <query>` | Search codebase and show matching context |
+| `/history` | Show conversation history |
+| `/help` | Show available commands |
+| `/quit` | Exit the chat |
+
+### `alexforge history`
+
+Show a list of previous autofix task runs.
+
+```bash
+alexforge history
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       CLI (Typer)                           │
+│ init │ index │ search │ analyze │ plan │ patch │ verify     │
+│ autofix │ cloud-chat │ diff │ rollback │ status │ chat │ history │
+└───────────────────────┬─────────────────────────────────────┘
+                        │
+           ┌────────────▼────────────┐
+           │   AgentOrchestrator     │
+           │  (coordinates pipeline) │
+           └────┬───┬───┬───┬───┬───┘
+                │   │   │   │   │
+     ┌──────────┘   │   │   │   └──────────┐
+     ▼              ▼   ▼   ▼              ▼
+┌─────────┐  ┌────────┐ ┌────────┐  ┌───────────┐
+│ Analyzer│  │Planner │ │ Coder  │  │ Verifier  │
+└─────────┘  └────────┘ └────────┘  └───────────┘
+                            │              │
+                     ┌──────┘     ┌────────┘
+                     ▼            ▼
+               ┌──────────┐ ┌──────────┐
+               │Reflector │ │Summarizer│
+               └──────────┘ └──────────┘
+
+     ┌─────────────────────────────────────────────┐
+     │              Support Layer                   │
+     │                                              │
+     │  ┌──────────────┐  ┌───────────────────┐    │
+     │  │  Repository   │  │  Context Manager  │    │
+     │  │   Indexer     │  │  (Budget + Asm.)  │    │
+     │  │  (SQLite)     │  │                   │    │
+     │  └──────────────┘  └───────────────────┘    │
+     │                                              │
+     │  ┌──────────────┐  ┌───────────────────┐    │
+     │  │  Retriever   │  │   File Patcher    │    │
+     │  │  + Ranking   │  │  (backup + apply) │    │
+     │  └──────────────┘  └───────────────────┘    │
+     │                                              │
+     │  ┌──────────────┐  ┌───────────────────┐    │
+     │  │ Ollama Client│  │ Verification      │    │
+     │  │  (httpx)     │  │   Runner          │    │
+     │  └──────────────┘  └───────────────────┘    │
+     └─────────────────────────────────────────────┘
+```
+
+### Component overview
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| **CLI** | `localforge/cli/` | Typer-based CLI with cloud and local commands |
+| **Agents** | `localforge/agent/` | 6 specialist agents + orchestrator |
+| **Chat** | `localforge/chat/` | Interactive local chat REPL with session persistence |
+| **Cloud Chat** | `localforge/cloud/` | Cloud client, auth handling, and autonomous cloud chat loop |
+| **Core** | `localforge/core/` | Config, data models, Ollama client, Git utils, prompt templates |
+| **Index** | `localforge/index/` | SQLite-backed code index + FTS5 search |
+| **Retrieval** | `localforge/retrieval/` | Multi-strategy context retrieval + ranking |
+| **Context Manager** | `localforge/context_manager/` | Token counting, budget allocation, prompt assembly |
+| **Patching** | `localforge/patching/` | File patching with backup, rollback, fuzzy matching |
+| **Verifier** | `localforge/verifier/` | Project detection + automated test/lint/type-check |
+
+---
+
+## Agent Loop
+
+The orchestrator drives a multi-phase loop. Each phase uses a dedicated agent
+with its own system prompt and structured JSON output schema.
+
+```
+                    ┌──────────────┐
+                    │  User Task   │
+                    └──────┬───────┘
+                           ▼
+                    ┌──────────────┐
+                    │  1. ANALYZE  │──── Understand the task & codebase
+                    └──────┬───────┘
+                           ▼
+                    ┌──────────────┐
+                    │  2. PLAN     │──── Produce ordered step list
+                    └──────┬───────┘
+                           ▼
+               ┌───────────────────────┐
+               │  For each plan step:  │
+               │  ┌──────────────────┐ │
+               │  │  3. CODE (patch) │ │
+               │  └────────┬─────────┘ │
+               │           ▼           │
+               │  ┌──────────────────┐ │
+               │  │  4. VERIFY       │ │
+               │  └────────┬─────────┘ │
+               │           │           │
+               │     pass? │  fail?    │
+               │      ▼    │    ▼      │
+               │   [next]  │ ┌──────┐  │
+               │           │ │REFLECT│  │
+               │           │ └──┬───┘  │
+               │           │    │      │
+               │           │  retry    │
+               │           │  (≤3x)    │
+               └───────────────────────┘
+                           ▼
+                    ┌──────────────┐
+                    │ 5. FINAL     │──── Full verification suite
+                    │    VERIFY    │
+                    └──────┬───────┘
+                           ▼
+                    ┌──────────────┐
+                    │ 6. SUMMARIZE │──── Generate change summary
+                    └──────────────┘
+```
+
+### Agent details
+
+| Agent | Input | Output | Purpose |
+|-------|-------|--------|---------|
+| **Analyzer** | Task + retrieved code + repo structure | Structured analysis (understanding, files, complexity) | Understand what needs to be done |
+| **Planner** | Analysis + code context | Ordered step list with file mappings | Break work into small, executable steps |
+| **Coder** | Plan step + file content + context | Search/replace patch (exact or full-file for CREATE) | Write the actual code change |
+| **Verifier** | Verification command output + step info | Pass/fail decision + next action | Interpret test/lint results |
+| **Reflector** | Failed attempts + error history | Revised approach instructions | Learn from failures and suggest alternatives |
+| **Summarizer** | All patches + verification results | Human-readable summary | Explain what was done |
+
+Each step retry includes the Reflector agent, which analyzes the failure and
+suggests a different approach. Maximum retries per step: **3**.
+
+---
+
+## How Retrieval Works
+
+AlexForge uses a multi-strategy retrieval pipeline (not just keyword search):
+
+1. **Query decomposition** — The task description is split into 3–5 focused
+   sub-queries: quoted strings, snake_case identifiers, CamelCase names, file
+   name hints, and significant keywords.
+
+2. **Multi-strategy search** — For each sub-query:
+   - **FTS5 lexical search** over indexed code chunks
+   - **Filename fuzzy matching** using SequenceMatcher
+   - **Symbol search** (function/class names) via SQL
+   - **ripgrep** integration (if available) for regex matches
+
+3. **Scoring and ranking** — Chunks are scored by:
+   - Lexical relevance (FTS5 rank)
+   - Term-frequency of query keywords in content
+   - Path relevance (filename matches task keywords)
+   - Recency (recently modified files get a boost)
+   - Deduplication penalty (similar chunks are penalized)
+
+4. **Token budget fitting** — Final chunks are greedily packed into the model's
+   context window, with high-value chunks truncated rather than dropped entirely.
+
+---
+
+## Project Rules
+
+Create `.localforge/rules.md` with your project conventions. These rules are
+automatically injected into every agent's system prompt.
+
+```markdown
+# Project Rules
+
+- Always use type hints in Python code
+- Follow PEP 8 style guidelines
+- Write docstrings for all public functions
+- Use `pytest` for testing with descriptive test names
+- Import ordering: stdlib, third-party, local (enforced by ruff)
+- All API endpoints must have error handling
+- Database queries must use parameterized statements
+```
+
+The agent will follow these rules when generating patches.
+
+---
+
+## Configuration Reference
+
+All configuration lives in `.localforge/config.yml`. Run `alexforge init` to
+generate a starter file.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model_name` | `string` | `qwen2.5-coder:7b` | Ollama model tag |
+| `ollama_base_url` | `string` | `http://localhost:11434` | Ollama HTTP API URL |
+| `max_context_tokens` | `int` | `16384` | Max tokens in LLM context window |
+| `max_iterations` | `int` | `50` | Max agent loop iterations |
+| `repo_path` | `string` | `.` | Repository root path |
+| `index_db_path` | `string` | `.localforge/index.db` | SQLite index location |
+| `auto_approve` | `bool` | `false` | Auto-approve patches |
+| `dry_run` | `bool` | `false` | Preview patches only |
+| `log_level` | `string` | `INFO` | Logging level |
+| `model_profile` | `string` | `small` | Profile: `small`, `medium`, `large` |
+
+### Environment variable overrides
+
+Variables prefixed with `LOCALFORGE_` override config values:
+
+```bash
+LOCALFORGE_MODEL_NAME=codellama:13b alexforge autofix "fix the bug"
+LOCALFORGE_MAX_CONTEXT_TOKENS=8192 alexforge autofix "refactor"
+```
+
+### Model Profiles
+
+| Profile | Context Window | Retrieval Limit | Chunk Size | Reasoning Depth |
+|---------|---------------|-----------------|------------|-----------------|
+| `small` | 8 192 | 5 | 512 | 2 |
+| `medium` | 8 192 | 10 | 1 024 | 4 |
+| `large` | 32 768 | 20 | 2 048 | 8 |
+
+---
+
+## Model Recommendations
+
+AlexForge works with any Ollama-compatible model. Tested recommendations:
+
+| Model | Size | Profile | Best For |
+|-------|------|---------|----------|
+| `qwen2.5-coder:7b` | 7 B | `small` | Fast iteration, simple fixes |
+| `qwen2.5-coder:14b` | 14 B | `medium` | Good balance of speed and quality |
+| `qwen2.5-coder:32b` | 32 B | `large` | Complex refactors, multi-file changes |
+| `codellama:13b` | 13 B | `medium` | Strong at code generation |
+| `deepseek-coder-v2:16b` | 16 B | `medium` | Excellent reasoning |
+| `llama3.1:8b` | 8 B | `small` | General-purpose, good at planning |
+
+**Tips:**
+
+- Start with `qwen2.5-coder:7b` on `small` profile — it's fast and capable.
+- Upgrade to a larger model only when you see plan quality issues.
+- The `large` profile with a 32 B+ model gives the best results but requires
+  significant VRAM (≥ 24 GB).
+- Set `max_context_tokens` to match your model's actual context window for best
+  results.
+
+---
+
+## Choosing and Switching Models
+
+AlexForge gives you three ways to work with models:
+
+### 1. List available models
+
+See all models you have pulled in your Ollama instance:
+
+```bash
+alexforge models
+```
+
+This displays all available models with a checkmark next to your current default.
+
+### 2. Set your default model
+
+Permanently change your default model for the project:
+
+```bash
+# Interactive selection (shows numbered list)
+alexforge set-model
+
+# Direct selection
+alexforge set-model qwen2.5-coder:14b
+```
+
+This updates `.localforge/config.yml` so all future commands use the new model.
+
+### 3. Override on a per-command basis
+
+Use `--model` (or `-m`) flag on **any** command that uses the LLM:
+
+```bash
+# One-time override for different commands
+alexforge autofix "fix the bug" --model codellama:13b
+alexforge chat --model qwen2.5-coder:32b
+alexforge plan "refactor" --model llama3.1:8b
+alexforge patch "fix" --model deepseek-coder-v2:16b
+alexforge analyze "slow endpoint" --model qwen2.5-coder:14b
+```
+
+The flag takes precedence over your default config.
+
+### Environment variable override
+
+For scripting or CI/CD, use environment variables:
+
+```bash
+export LOCALFORGE_MODEL_NAME=qwen2.5-coder:14b
+alexforge autofix "fix the bug"
+```
+
+### Quick model switching workflow
+
+```bash
+# 1. See available models
+alexforge models
+
+# 2. Try a model on one command
+alexforge autofix "small fix" --model llama3.1:8b
+
+# 3. If you like it, make it the default
+alexforge set-model llama3.1:8b
+
+# 4. All future commands use it
+alexforge autofix "bigger task"
+```
+
+---
+
+## Workflow Examples
+
+### Fix a bug
+
+```bash
+alexforge init
+alexforge index
+alexforge autofix "fix the null pointer exception in UserService.get_by_id"
+```
+
+### Add a feature
+
+```bash
+alexforge autofix "add pagination to the GET /users endpoint with page and limit query params"
+```
+
+### Targeted step-by-step
+
+```bash
+# 1. See what context the agent has
+alexforge analyze "refactor database module to use connection pooling"
+
+# 2. Generate a plan (review before executing)
+alexforge plan "refactor database module to use connection pooling"
+
+# 3. Execute step-by-step with manual approval
+alexforge patch "refactor database module to use connection pooling"
+
+# 4. Or execute a single step
+alexforge patch "refactor database module to use connection pooling" --step 2
+
+# 5. Verify the changes
+alexforge verify
+```
+
+### Dry-run (preview without changes)
+
+```bash
+alexforge autofix "add error handling to all API endpoints" --dry-run
+```
+
+### With a different model
+
+```bash
+alexforge autofix "optimize the database queries" --model qwen2.5-coder:32b --profile large
+```
+
+### Code exploration
+
+```bash
+# Search for functions related to auth
+alexforge search "authenticate" --mode symbol
+
+# Find files matching a pattern
+alexforge search "database" --mode filename
+
+# Full-text search
+alexforge search "connection pool" --mode text
+```
+
+### Chat with your codebase
+
+```bash
+# Start an interactive chat session
+alexforge chat
+
+# In the chat:
+# > How does the authentication flow work?
+# > What would break if I changed the User model?
+# > /context database connection pooling
+# > Can you explain the retrieval pipeline?
+```
+
+### Undo changes
+
+```bash
+# List available backups
+alexforge rollback
+
+# Restore to a specific backup
+alexforge rollback 20260403T143022
+
+# Or use the diff command to review changes first
+alexforge diff
+```
+
+### Debug mode
+
+```bash
+# See exactly what the agent is doing
+alexforge --verbose autofix "fix the bug in auth.py"
+```
+
+---
+
+## Safety & Backups
+
+AlexForge is designed to be safe by default:
+
+| Safety Feature | Description |
+|----------------|-------------|
+| **File backups** | Every file is backed up to `.localforge/backups/<timestamp>/` before any patch is applied |
+| **Diff preview** | Every patch is displayed as a unified diff before application |
+| **Confirmation prompt** | Patches require explicit `y` approval unless `--yes` is passed |
+| **Dry-run mode** | Use `--dry-run` to preview all changes without writing anything |
+| **Rollback** | `alexforge rollback <timestamp>` restores any backup state |
+| **Verification** | After patching, the agent runs lint, type-check, and tests automatically |
+| **Patch validation** | Patches are validated for syntax correctness and scanned for dangerous patterns (eval, os.system, hardcoded secrets, etc.) |
+| **Path traversal protection** | File paths are validated to stay within the repository root |
+| **Iteration cap** | The agent stops after `max_iterations` (default: 50) to prevent runaway loops |
+| **No network** | All processing happens locally via Ollama. Zero external network calls |
+
+---
+
+## Tips for Best Results
+
+1. **Be specific in your task description.** Instead of "fix the bug", say "fix
+   the null check in `UserService.get_by_id` that causes a crash when the user
+   doesn't exist".
+
+2. **Index frequently.** Run `alexforge index` after major changes so the agent
+   has fresh context. Incremental indexing is fast.
+
+3. **Use `analyze` first.** Before running `autofix`, use `alexforge analyze`
+   to preview what code the agent will see. If the relevant code isn't in the
+   results, adjust your task description.
+
+4. **Start with `plan`.** For complex tasks, run `alexforge plan` first to
+   review the generated plan before execution.
+
+5. **Use project rules.** Add your coding conventions to `.localforge/rules.md`
+   — the agent quality improves significantly when it knows your standards.
+
+6. **Match the profile to your model.** A `small` profile with a 7B model is
+   faster and often sufficient. Only use `large` when the task genuinely needs
+   a bigger context window.
+
+7. **Review patches carefully.** Even with verification, AI-generated patches
+   should be reviewed. The diff preview exists for a reason.
+
+8. **Use `search` for exploration.** The `alexforge search` command is a fast
+   way to explore your codebase using the same index the agent uses.
+
+---
+
+## Limitations
+
+AlexForge is alpha software. Known limitations:
+
+| Limitation | Detail |
+|------------|--------|
+| **No semantic embedding search** | Retrieval is lexical + symbol-based. The embedding API exists but is not yet integrated into the search pipeline. |
+| **No multi-repo support** | Operates on one repository at a time. |
+| **LLM quality ceiling** | Output quality is bounded by the local model. Small models may produce incorrect patches for complex tasks. |
+| **Context window pressure** | Very large files may be truncated to fit the token budget. Auto-detection helps, but some models still have small context windows. |
+| **No runtime debugging** | The agent cannot set breakpoints or inspect runtime state. |
+
+---
+
+## Comparison with Cloud Agents
+
+| Capability | AlexForge | Claude Code / Cursor |
+|------------|------------|----------------------|
+| **Privacy** | 100 % local, code never leaves machine | Code sent to cloud APIs |
+| **Cost** | Free (uses your GPU) | Per-token or subscription billing |
+| **Offline** | Fully offline | Requires internet |
+| **Multi-agent** | 6 specialist agents with structured handoffs | Typically single-agent |
+| **Interactive chat** | Yes (`alexforge chat` with persistent history) | Yes |
+| **Streaming output** | Yes (token-by-token) | Yes |
+| **Git integration** | Auto-checkpoints before/after changes | Varies |
+| **Code search** | SQLite FTS5 + symbols + ripgrep | Embedding-based or none |
+| **Multi-language** | Python, JS/TS, Go, Rust, Java, C#, Ruby, PHP, C/C++ | Yes |
+| **Safety** | Backup + diff + confirm + rollback + validation | Varies |
+| **Token awareness** | Explicit budget management + auto-detect context window | May silently truncate |
+| **Verification** | Auto-detects & runs pytest, ruff, mypy, npm test, go test | Usually manual |
+| **Project rules** | `.localforge/rules.md` injected into all prompts | `.cursorrules` / CLAUDE.md |
+| **Model quality** | Limited by local hardware (7B–70B) | GPT-4, Claude 3.5, etc. |
+
+**Where AlexForge wins:** privacy, cost, offline use, transparency, safety
+features, multi-agent architecture, token budget management, zero configuration.
+
+**Where cloud agents win:** model quality (access to frontier models), semantic
+search, larger context windows, faster inference on large models.
+
+---
+
+## Changelog
+
+### v0.4.0
+
+- **Tool-use from chat.** The chat engine now supports autonomous tool
+  execution — the LLM can read files, write files, edit code, run shell
+  commands, and search the codebase on its own, similar to Claude Code.
+- **New slash commands.** `/run <cmd>` to execute shell commands, `/read <path>`
+  to read files, `/tokens` to see session token usage — all from within chat.
+- **Shell execution safety.** Destructive commands (`rm`, `del`, `format`, etc.)
+  are blocked. Output is truncated at 20KB. Commands time out after 60 seconds.
+- **Path traversal hardening.** Uses `Path.is_relative_to()` instead of string
+  prefix checks for cross-platform safety.
+- **Chat context window auto-detect.** The `chat` command now auto-detects the
+  model's context window, matching the `autofix` command's behavior.
+- **Resource cleanup fixes.** Async `ollama.close()` now runs in the same event
+  loop for both `chat` and `patch` commands, preventing resource leaks.
+- **Orchestrator path fix.** File reading during plan execution now correctly
+  resolves repo-relative paths instead of relying on CWD.
+- **Version sync fix.** `__init__.py` and `pyproject.toml` versions are now
+  consistent.
+- **New: 132 tests** (up from 109).
+- Version bump to 0.4.0.
+
+### v0.3.0
+
+- **Interactive chat.** `alexforge chat` — conversational REPL with codebase
+  context retrieval, persistent chat history, and slash commands.
+- **Streaming output.** Model responses now stream token-by-token to the
+  terminal instead of showing only a spinner.
+- **Auto-detect context window.** Queries the Ollama `/api/show` endpoint to
+  determine the model's actual context window size automatically.
+- **Git integration.** Automatic git checkpoints before and after `autofix`
+  runs. The `status` command now shows git branch and changed files.
+- **Enhanced symbol extraction.** Full support for Python (async, constants),
+  JavaScript/TypeScript (const/let/var exports, interfaces, types, enums),
+  Go (methods with receivers, struct/interface), Rust (pub fn, struct, enum,
+  trait, impl), Java/Kotlin/C# (classes, interfaces, enums, methods),
+  Ruby (modules), PHP, and C/C++.
+- **Task history.** `alexforge history` command shows previous autofix runs.
+- **Patch safety.** The patcher now runs safety and syntax validation before
+  applying patches, with interactive warnings for dangerous operations.
+- **New: 109 tests** (up from 86).
+- Version bump to 0.3.0.
+
+### v0.2.0
+
+- Added `alexforge search` command (text, filename, symbol modes).
+- Added `alexforge rollback` command.
+- Added `--verbose`/`--debug` flag with logging.
+- Added project rules injection from `.localforge/rules.md`.
+- Fixed: removed unnecessary Ollama check from `index` command.
+- Fixed: converted smoke tests from inline scripts to proper pytest format.
+- Comprehensive README.
+
+### v0.1.0
+
+- Initial release with full multi-agent pipeline.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+```bash
+# Development setup
+git clone https://github.com/alexforge/localforge.git
+cd alexforge
+pip install -e ".[dev]"
+
+# Run tests
+python -m pytest tests/ -v
+
+# Lint
+ruff check .
+
+# Type check
+mypy alexforge/
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).