{"id":51487869,"url":"https://github.com/maz557/coding-agent-free","last_synced_at":"2026-07-07T09:00:29.470Z","repository":{"id":367455097,"uuid":"1277579919","full_name":"maz557/coding-agent-free","owner":"maz557","description":"Interactive AI coding agent using free OpenRouter models with real tool calling","archived":false,"fork":false,"pushed_at":"2026-07-05T05:58:14.000Z","size":138,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-05T06:12:22.793Z","etag":null,"topics":["agent","ai-agent","cli","code-generation","coding-agent","free","free-llm","full-stack","groq","llamacpp","llm","llm-agents","llm-tools","lm-studio","local-llm","ollama","openrouter","programming","tool-calling","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/maz557/coding-agent-free","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maz557.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-23T02:38:38.000Z","updated_at":"2026-07-05T05:58:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maz557/coding-agent-free","commit_stats":null,"previous_names":["maz557/coding-agent-free"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/maz557/coding-agent-free","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maz557%2Fcoding-agent-free","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maz557%2Fcoding-agent-free/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maz557%2Fcoding-agent-free/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maz557%2Fcoding-agent-free/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maz557","download_url":"https://codeload.github.com/maz557/coding-agent-free/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maz557%2Fcoding-agent-free/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35221308,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai-agent","cli","code-generation","coding-agent","free","free-llm","full-stack","groq","llamacpp","llm","llm-agents","llm-tools","lm-studio","local-llm","ollama","openrouter","programming","tool-calling","typescript"],"created_at":"2026-07-07T09:00:17.963Z","updated_at":"2026-07-07T09:00:29.414Z","avatar_url":"https://github.com/maz557.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Coding Agent Free\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/github/stars/maz557/coding-agent-free?style=for-the-badge\u0026logo=github\" alt=\"Stars\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/maz557/coding-agent-free?style=for-the-badge\" alt=\"License\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/last-commit/maz557/coding-agent-free?style=for-the-badge\u0026logo=git\" alt=\"Last Commit\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-6.x-3178C6?style=for-the-badge\u0026logo=typescript\" alt=\"TypeScript\"/\u003e\n  \u003cimg src=\"https://img.shields.io/github/actions/workflow/status/maz557/coding-agent-free/ci.yml?branch=main\u0026style=for-the-badge\u0026logo=githubactions\" alt=\"CI\"/\u003e\n  \u003cbr/\u003e\n  \u003ca href=\"#-why-this-agent\"\u003e\u003cstrong\u003eWhy This Agent?\u003c/strong\u003e\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003e\u003cstrong\u003eQuick Start\u003c/strong\u003e\u003c/a\u003e •\n  \u003ca href=\"#cli-interface\"\u003e\u003cstrong\u003eCLI\u003c/strong\u003e\u003c/a\u003e •\n  \u003ca href=\"#web-interface\"\u003e\u003cstrong\u003eWeb\u003c/strong\u003e\u003c/a\u003e •\n  \u003ca href=\"#example-interactions\"\u003e\u003cstrong\u003eExamples\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  🌐\n  \u003ca href=\"README.md\"\u003e\u003cstrong\u003eEnglish\u003c/strong\u003e\u003c/a\u003e •\n  \u003ca href=\"README.fa.md\"\u003eفارسی\u003c/a\u003e •\n  \u003ca href=\"README.ar.md\"\u003eالعربية\u003c/a\u003e •\n  \u003ca href=\"README.tr.md\"\u003eTürkçe\u003c/a\u003e •\n  \u003ca href=\"README.es.md\"\u003eEspañol\u003c/a\u003e •\n  \u003ca href=\"README.fr.md\"\u003eFrançais\u003c/a\u003e •\n  \u003ca href=\"README.ur.md\"\u003eاردو\u003c/a\u003e\n\u003c/p\u003e\n\nAn interactive AI coding assistant that runs in your **terminal** or **web browser** — powered by **free** cloud APIs (OpenRouter, Groq, Google, DeepSeek, Mistral) and **local** models (Ollama, LM Studio, Llama.cpp). It reads, writes, searches, copies, moves, and deletes files, and runs shell commands — all through natural language tool calling.\n\n\u003e 💡 **Offline-ready**: With a local server, the agent works fully offline — no internet required, no data leaves your machine.\n\n## 🧠 Why This Agent?\n\n| Problem | How This Agent Solves It |\n|---------|--------------------------|\n| Coding assistants cost $20/month (ChatGPT+, Claude Pro) | **100% free** — uses free-tier OpenRouter, Groq, Google, DeepSeek, Mistral + local models |\n| One provider goes down / rate-limited | **8 providers** — auto-fallback on 429 + manual `/model \u003cn\u003e` |\n| No internet access / restricted region | **Local models** (Ollama, LM Studio, Llama.cpp) — fully offline |\n| Privacy concerns with cloud APIs | Run **local models only** — zero data leaves your machine |\n| Setup is too complex | **`npm run setup`** — interactive wizard, no manual `.env` editing |\n| AI runs dangerous commands | **Safe mode** (`/safe`) — whitelist-only shell commands |\n| Agent gets stuck in loops | **Smart detection** — stops after 3× identical tool calls |\n| Provider rate-limited | **Auto-fallback** — switches provider automatically on 429 |\n| Long tool results waste tokens | **Token compression** — head+tail truncation + duplicate removal |\n| Want to use your IDE with free models | **OpenAI-compatible API** — `npm run setup-ide` connects Cline, Continue.dev, Cursor |\n\n## Quick Start\n\n```bash\ngit clone https://github.com/maz557/coding-agent-free.git\ncd coding-agent-free\nnpm install\n```\n\nRun the interactive setup wizard (recommended):\n```bash\nnpm run setup\n```\n\nOr create `.env` manually (pick at least one provider):\n```bash\n# OpenRouter (easiest — single key for 18+ free tool-calling models)\necho \"OPENROUTER_API_KEY=sk-or-v1-...\" \u003e\u003e .env\n\n# Optional providers:\necho \"GROQ_API_KEY=gsk_...\" \u003e\u003e .env      # Ultra-fast inference\necho \"GOOGLE_API_KEY=AIza...\" \u003e\u003e .env     # Gemini models\necho \"DEEPSEEK_API_KEY=sk-...\" \u003e\u003e .env    # DeepSeek\necho \"MISTRAL_API_KEY=...\" \u003e\u003e .env        # Mistral models\n```\n\n**Fully offline (no API keys needed):**\n```bash\n# 1. Clone and install (requires internet once)\ngit clone https://github.com/maz557/coding-agent-free.git\ncd coding-agent-free\nnpm install\n\n# 2. Start your local model server (pick one):\n#    ollama run qwen3:14b           # Ollama\n#    # or run LM Studio / llama-server\n\n# 3. Launch the agent:\nnpm start\n\n# 4. Inside the agent, add your local model:\n#    You: /add 6 ollama:auto\n#    You: /model 6\n```\n\n## CLI Interface\n\n```bash\nnpm start\n```\n\n\u003e On Windows, double-click `run-cli.bat`.\n\u003e 📝 **RTL languages (Persian, Arabic, Urdu, Hebrew, etc.):** If your terminal displays right-to-left text incorrectly, use `run-cli-rtl.bat` instead — it launches via [WezTerm](https://wezfurlong.org/wezterm/) with proper BiDi support.\n\n## Web Interface\n\n```bash\nnpm run web\n# Open http://localhost:3000 in your browser\n```\n\n\u003e On Windows, double-click `run-web.bat`.\n\nThe web UI supports the same features as the terminal — streaming responses, tool calls, model switching (all 8 providers + user presets), safe mode toggle, allow path, and conversation reset. Multiple browser tabs are supported with independent sessions. CLI and Web share the same model configuration (`src/config/models.ts`) and tool engine (`fileManager.ts`).\n\n**New in v1.10 — Web UI enhancements:**\n- **Diff Viewer** — when a file is written, replaced, or appended, the UI shows a side-by-side line-level diff (green + / red –) so you can see exactly what changed.\n- **Session Manager** — create multiple sessions, switch between them, see auto-generated titles from the first message, model used, and message count.\n- **Slash Commands** — type `/active`, `/model 2`, `/safe`, `/allow \"C:\\path\"`, `/reset`, `/models`, `/exit` directly in the web input.\n- **Help Modal** — click the `?` button for a complete usage guide including model switching, commands reference, and diff viewer explanation.\n- **SSE streaming** — uses `fetch` + `ReadableStream` (no `EventSource` dependency) for reliable streaming.\n\nThe web server also exposes an **OpenAI-compatible API** at `http://localhost:3000/v1/chat/completions`, so any OpenAI-compatible client (Cline, Continue.dev, Cursor, etc.) can use your configured providers through a single endpoint with auto-fallback support.\n\nConfigure your IDE automatically:\n```bash\nnpm run setup-ide\n```\n\nThis will configure **Cline**, **Continue.dev**, and **Cursor** to point to the local API proxy, using your `.env` provider keys through the same routing.\n\n**Example session:**\n\n```\n┌──────────────────────────────────────────────────────────┐\n│  💬 Coding Agent                       [🔒 Safe] [🌐 P] │\n│  ──────────────────────────────────────────────────────── │\n│                                                          │\n│  You: create a hello.py that prints \"Hello from Web UI\"  │\n│                                                          │\n│  ⏳ Thinking... [Model: openrouter/free]                 │\n│                                                          │\n│  🛠  write_file(path=\"hello.py\", content=\"...\")          │\n│  ✔  File written (25 bytes)                              │\n│                                                          │\n│  🛠  run_command(command=\"python hello.py\")              │\n│  ✔  Hello from Web UI                                    │\n│                                                          │\n│  Done! Created hello.py and verified it prints:          │\n│  Hello from Web UI                                       │\n│  ──────────────────────────────────────────────────────── │\n│  [Message input...                        ] [Send]       │\n└──────────────────────────────────────────────────────────┘\n```\n\n\u003e The model dropdown lets you switch between all 8 providers and your saved presets mid-session. Streaming responses appear token-by-token in real time.\n\u003e Click the **`?`** button in the header to open a help modal with usage guide, model switching instructions, and CLI command equivalents.\n\n## Example Interactions\n\n**\"Create a Python script that prints Fibonacci numbers\"**\n\nThe agent will create the file, write the code, then run it to verify:\n\n```\nYou: write a fibonacci.py that prints first 20 numbers\n⏳ Thinking...\n  🔧 write_file({\"path\":\"fibonacci.py\",\"content\":\"...\"})\n  🔧 run_command({\"command\":\"python fibonacci.py\"})\nAgent: Done! Created fibonacci.py and verified output: 0, 1, 1, 2, 3, 5...\n```\n\n**\"Find all TypeScript files that call fetch() and replace it with axios\"**\n\n```\nYou: find all .ts files with fetch() calls and change them to axios\n  🔧 search_content({\"pattern\":\"fetch(\",\"filePattern\":\"*.ts\"})\n  🔧 read_file({\"path\":\"src/api.ts\"})\n  🔧 replace_in_file({\"path\":\"src/api.ts\",\"old_str\":\"fetch(\",\"new_str\":\"axios.\"})\nAgent: Updated 3 files (api.ts, users.ts, auth.ts).\n```\n\n**\"Debug this error: Cannot read property 'map' of undefined\"**\n\nThe agent reads the relevant file, analyzes the code, suggests and applies a fix.\n\n## Features\n\n- **8 providers** — OpenRouter, Groq, Google, DeepSeek, Mistral + Ollama, LM Studio, Llama.cpp\n- **5 built-in presets** — start with `openrouter/free` (auto-discovers working free models)\n- **User presets** — save/add/remove your own models with `/save`, `/add`, `/remove`\n- **Fallback chain** — auto-fallback across providers on rate limit (429), plus model-level fallbacks\n- **13 tools** — read, write, list (with details), create_folder, delete_file, delete_folder (recursive), append_file, copy_file, move_file, file_info, search_content, replace_in_file, and run_command\n- **Token compression** — head+tail truncation of long tool results + automatic duplicate removal\n- **Sliding window context** — keeps the last 20 exchanges by default, auto-trims to avoid token limit errors (configurable via `MAX_EXCHANGES` / `MAX_TOOL_RESULT_LENGTH`)\n- **Smart loop detection** — stops if a tool is called 3+ times identically or 5+ times consecutively\n- **Safe mode** (`--safe` / `/safe`) — whitelist-only shell commands\n- **Setup wizard** — `npm run setup` interactively configures .env\n- **Automatic retry** — exponential backoff + 120s timeout (300s for local models)\n- **Zod validation** — runtime type-checking of every tool input and output\n- **CLI \u0026amp; Web unified** — shared model config, system prompt, tool engine, provider definitions, and user presets across both interfaces\n- **AGENTS.md support** — drop `AGENTS.md` in your project root to give the agent project-specific context automatically\n- **opencode.json** — comprehensive permission rules (100+ safe command patterns auto-allowed) and truncated tool output for cleaner prompts\n- **Tool output truncation** — all tool results capped at 5000 chars (`MAX_TOOL_RESULT_LENGTH`) to keep context clean\n- **Conversation persistence** — auto-save/restore sessions across restarts\n- **Structured logging** — via `pino` (stderr, doesn't interfere with UI)\n- **Diff Viewer (Web UI)** — line-level LCS diffs for `write_file`, `replace_in_file`, `append_file`\n- **Session Manager (Web UI)** — create/switch/list sessions with auto-title \u0026 metadata\n- **Slash Commands (Web UI)** — `/active`, `/model \u003cn\u003e`, `/safe`, `/allow`, `/reset`, `/models`, `/exit`\n- **Help Modal (Web UI)** — usage guide, commands reference, diff viewer explanation\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `read_file` | Read contents of a file |\n| `write_file` | Write content to a file (creates/overwrites) |\n| `list_files` | List directory contents. Use `details:true` for size + timestamps |\n| `create_folder` | Create a new folder |\n| `delete_file` | Delete a single file |\n| `delete_folder` | Delete a folder. Set `recursive:true` for non‑empty folders |\n| `append_file` | Append content to an existing file |\n| `copy_file` | Copy a file from source to destination |\n| `move_file` | Move or rename a file |\n| `file_info` | Get detailed metadata (size, permissions, timestamps) |\n| `search_content` | Search for exact text in files. Supports `filePattern` (e.g. `*.ts`) and `maxResults` (default 50). Skips files \u003e1MB |\n| `replace_in_file` | Replace the first occurrence of exact text (case‑sensitive) |\n| `run_command` | Run a shell command in the workspace |\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/model \u003cn\u003e` | Switch to preset n |\n| `/save \u003cn\u003e` | Save current model as preset n |\n| `/add \u003cn\u003e \u003cm\u003e` | Add model m as preset n (`provider:model` or just `model`) |\n| `/remove \u003cn\u003e` | Remove a user preset |\n| `/allow \u003cp\u003e` | Allow model to access a path outside workspace |\n| `/safe` | Toggle safe mode (whitelist-only shell commands) |\n| `/models` | Show all presets |\n| `/active` | Show current active model |\n| `/reset` | Clear conversation history (start fresh) |\n| `/list-providers` | Show providers with valid keys (and local providers) |\n| `/exit` | Quit |\n\n## Multi-Provider Usage\n\nEach preset is tied to a provider. Switching presets with `/model \u003cn\u003e` recreates the API client automatically:\n\n```\nYou: /add 6 groq:openai/gpt-oss-120b\n✅ Added preset 6: [Groq] openai/gpt-oss-120b\n\nYou: /model 6\n✅ Switched to preset 6: [Groq] openai/gpt-oss-120b\n   (now using Groq's API with gpt-oss-120b)\n\nYou: /model 1\n✅ Switched to preset 1: [OpenRouter] openrouter/free\n   (back to OpenRouter)\n```\n\n### Adding models from other providers\n\n```\n/add \u003cn\u003e \u003cprovider\u003e:\u003cmodel-id\u003e\n```\n\nExamples:\n```\n/add 10 groq:llama-3.3-70b-versatile\n/add 11 google:gemini-2.0-flash-exp\n/add 12 deepseek:deepseek-chat\n/add 13 mistral:codestral-latest\n```\n\nIf you omit the provider (e.g. `/add 10 llama-3.3-70b-versatile`), it defaults to the current preset's provider.\n\n## Local Models (Ollama, LM Studio, Llama.cpp)\n\nThe agent supports any OpenAI-compatible local server with zero configuration:\n\n### Quick start\n\nMake sure your local server is running, then:\n\n```\nYou: /add 6 ollama:auto\n✅ Auto-detected model: llama3.2:latest\n✅ Added preset 6: [Ollama] llama3.2:latest\n\nYou: /model 6\n✅ Switched to preset 6: [Ollama] llama3.2:latest\n```\n\nOr for LM Studio:\n\n```\nYou: /add 7 lmstudio:auto\n✅ Added preset 7: [LM Studio] qwen2.5-coder-7b-instruct\n```\n\nThe `:auto` keyword tells the agent to connect to the local server and detect the loaded model automatically.\n\n### Quick start — specific local model\n\n```bash\n# Ollama — pull and serve a tool-calling model\nollama pull llama3.2\nollama serve                  # starts on port 11434\n\n# Llama.cpp — serve a GGUF model directly\nllama-server -m qwen2.5-coder-1.5b-instruct-q4_k_m.gguf --port 8080\n\n# LM Studio — uses the built-in lms CLI\nlms get llama-3.2-3b-instruct   # download a model\nlms load llama-3.2-3b-instruct  # load into memory\nlms server start --port 1234    # start the API server\n```\n\nThen add the local model to the agent:\n```\n/add 6 ollama:auto\n/add 7 lmstudio:auto\n/add 8 llamacpp:auto\n```\n\n### Custom ports\n\nSet in `.env`:\n```bash\nOLLAMA_HOST=http://localhost:11434/v1\nLMSTUDIO_HOST=http://localhost:1234/v1\nLLAMACPP_HOST=http://localhost:8080/v1\n```\n\n### Requirements\n\n- **Ollama**: [Download](https://ollama.ai) → `ollama pull llama3.2` → `ollama serve`\n- **LM Studio**: [Download](https://lmstudio.ai) → `lms get llama-3.2-3b-instruct` → `lms server start --port 1234`\n- **Llama.cpp**: [Download](https://github.com/ggerganov/llama.cpp) → Build or get a binary → `llama-server -m model.gguf --port 8080`\n- The model must support **tool calling** (function calling) for full agent functionality.\n- No API key required — local providers are skipped during startup key validation.\n- All local providers use the OpenAI-compatible API, so no additional packages are needed.\n\n## Workspace \u0026 Permissions\n\nBy default, the agent can only access files inside `./workspace`. To access other paths:\n\n### Option 1: Change default workspace (permanent)\n\nSet `ALLOWED_DIR` in `.env`:\n```\nALLOWED_DIR=.          # project root — access everything\nALLOWED_DIR=C:\\path    # any absolute path\n```\n\n### Option 2: Allow paths on-demand (per session)\n\nWhen the model tries to access a path outside the workspace:\n```\n❌ Tool Error: Access denied: \"C:\\path\" is outside the allowed directory.\n   Use command: /allow \"C:\\path\"\n```\n\nGrant access with:\n```\nYou: /allow \"C:\\path\"\n✅ Allowed: C:\\path\n```\n\nPermissions last for the current session only.\n\n## Built-in Presets\n\n| # | Model | Provider | Speed | Notes |\n|---|-------|----------|-------|-------|\n| 1 | `openrouter/free` | OpenRouter | varies | Auto-routes to available free models |\n| 2 | Qwen 3 Next 80B | OpenRouter | medium | Good general purpose |\n| 3 | Nemotron 3 Super 120B | OpenRouter | medium | 1M context |\n| 4 | OpenAI GPT-OSS 120B | OpenRouter | fast | Strong reasoning |\n| 5 | Nemotron 3 Ultra 550B | OpenRouter | slow | Largest free model with tools |\n\n## Recommended Free Coding Models by Provider\n\n### OpenRouter\nUse the `openrouter/free` router, or pin specific models with `/add \u003cn\u003e \u003cmodel\u003e:free`.\n\n### Groq (fastest — LPU hardware)\n```\n/add 6 groq:openai/gpt-oss-120b       # 120B, 500 t/s\n/add 7 groq:llama-3.3-70b-versatile   # 70B, 280 t/s\n/add 8 groq:qwen/qwen3-32b            # 32B, 400 t/s\n/add 9 groq:meta-llama/llama-4-scout-17b-16e-instruct  # 750 t/s\n```\nRate limits: 30 RPM, ~1K RPD. All models support tool calling.\n\n### Mistral (EU-hosted)\n```\n/add 10 mistral:codestral-latest       # Dedicated coding model\n/add 11 mistral:mistral-large-latest   # Best quality\n/add 12 mistral:mistral-small-latest   # Lightweight \u0026 fast\n/add 13 mistral:open-mistral-nemo      # 128K context, open-weight\n```\nFree tier: ~1 req/s, 1B tokens/month.\n\n### Google AI Studio\n```\n/add 14 google:gemini-2.0-flash-exp    # Fast, good coding\n```\nFree tier: 5-15 RPM, 100-1K RPD.\n\n### DeepSeek\n```\n/add 15 deepseek:deepseek-chat         # General purpose\n/add 16 deepseek:deepseek-reasoner     # Strong reasoning\n```\nFree tier: ~500 RPM, 500M tokens/day.\n\n## Example Session\n\n```\nYou: /model 4\n✅ Switched to preset 4: openai/gpt-oss-120b:free\n\nYou: create a folder named demo and write a hello.py\n⏳ Thinking...\n  [Model: openai/gpt-oss-120b:free]\n  🔧 create_folder({\"path\":\"demo\"})\n  🔧 write_file({\"path\":\"demo/hello.py\",\"content\":\"print('Hello, world!')\\n\"})\nAgent: Done! Created demo/hello.py with a Hello World script.\n\nYou: run the file\n⏳ Thinking...\n  [Model: openai/gpt-oss-120b:free]\n  🔧 run_command({\"command\":\"python demo/hello.py\"})\nAgent: Hello, world! — the script runs correctly.\n\nYou: /model 6\n✅ Switched to preset 6: [Groq] openai/gpt-oss-120b\n   (now using Groq — same model, 500 t/s)\n\nYou: list files\n⏳ Thinking...\n  [Model: openai/gpt-oss-120b]\n  🔧 run_command({\"command\":\"ls -la\"})\nAgent: demo/hello.py  ...\n```\n\n## Troubleshooting\n\n| Error | Likely Cause | Fix |\n|-------|-------------|------|\n| `403 Forbidden` | API key missing or invalid | Check `.env` has the right key for that provider |\n| `403 Forbidden` | Internet restrictions blocking API host | Enable VPN/proxy, set `HTTPS_PROXY`, or use local models: `/add 6 ollama:auto` |\n| `429 Rate limit exceeded` | Free tier daily limit hit | Wait or let **auto-fallback** switch provider automatically. Manual: `/model \u003cn\u003e` |\n| `Agent stopped: stuck detected` | Same tool called 3×+ consecutively | Recovery message injected automatically — rephrase your request |\n| `All 3 attempts failed` | Model unreachable or too slow | Try a smaller model, use local models, or switch provider with `/model \u003cn\u003e` |\n| `tool_calls` with empty arguments | Model doesn't support tool calling | Use a different model |\n| `ENOTFOUND` / `ECONNREFUSED` | Internet restrictions or proxy needed | Enable VPN/proxy, set `HTTPS_PROXY`, or use local models |\n\n### Quick checks\n- `/list-providers` — shows which API keys are configured\n- `/safe` — toggle safe mode status\n- `npm run setup` — re-run the setup wizard\n- `npm start` — restart after any code update\n\n## Project Structure\n\n```\ncoding-agent-free/\n├── src/\n│   ├── agent.ts                # CLI entry point\n│   ├── CodingAgent.ts          # Agent loop, tool execution, stuck detection\n│   ├── ConversationState.ts    # Sliding window, context trimming, message management\n│   ├── commands.ts             # Preset formatting, showModels\n│   ├── detectLocalModel.ts     # Auto-detect models on local providers\n│   ├── persistence.ts          # Save/load conversation \u0026 presets (with Zod validation)\n│   ├── tokenEstimator.ts       # Token estimation (length/4)\n│   ├── types.ts                # Shared type definitions (ChatMessage, ToolCall, etc.)\n│   ├── validation.ts           # Zod schemas for tool input/output\n│   ├── server.ts               # Express web server (SSE streaming, session management, auto-title)\n│   ├── config/\n│   │   └── models.ts           # Provider definitions, presets, system prompt\n│   ├── tools/\n│   │   └── fileManager.ts      # 13 tools + safe mode + workspace restrictions\n│   └── __tests__/              # Unit tests\n│       ├── ConversationState.test.ts  # 9 tests: trim, removeLastAssistantTurn, etc.\n│       ├── comprehensive.test.ts      # 30 tests: all modules + integration\n│       ├── CodingAgent.test.ts        # 11 tests: execute, stuck, retry, errors\n│       ├── loadProjectContext.test.ts  # 7 tests: file lookup, walk, edge cases\n│       ├── fileManager.test.ts        # 26 tests: all 13 tools + safe mode\n│       ├── agent.test.ts              # 24 tests: CLI commands, regex parsing, createClient\n│       └── server.test.ts             # 30 tests: API endpoints, session, safe-mode, proxy, diff events\n├── .github/\n│   └── workflows/\n│       └── ci.yml              # CI: type check + tests on push/PR\n├── scripts/\n│   ├── check_models.js         # List free OpenRouter models with tool support\n│   ├── cleanup.js              # Kill stale processes on port 3000\n│   ├── comprehensive-test.js   # 35 integration tests (npm test)\n│   ├── provider-integration-test.ts  # 26 provider integration tests (npm run test:integration)\n│   ├── setup.js                # Interactive setup wizard (npm run setup)\n│   ├── setup-ide.js            # Configure IDEs to use local API proxy\n│   ├── test.js                 # Non-interactive CLI smoke test\n│   ├── test-improvements.js\n│   ├── tool-integration-test.ts\n│   └── wezterm-launcher.cmd    # Helper for run-cli-rtl.bat\n├── local/                      # Local tools (gitignored)\n│   ├── backup/src/             # Snapshot of src/ for quick rollback\n│   └── restore.ps1             # Restore src/ from backup\n├── workspace/                  # Default working directory\n├── .env                        # API keys (gitignored)\n├── presets.json                # User presets (gitignored)\n├── tsconfig.json\n├── AGENTS.md                   # Project-specific agent context (auto-loaded)\n├── run-cli.bat                 # CLI launcher (Windows)\n├── run-cli-rtl.bat             # CLI launcher with RTL support (WezTerm)\n└── run-web.bat                 # Web UI launcher (Windows)\n```\n\n\u003e 📝 Run tests: `npm run test:unit` (137 unit tests) — `npm run test:integration` (26 provider tests) — `npm test` (35 integration tests)\n\n## Environment Variables\n\n| Variable | Required? | Description |\n|----------|-----------|-------------|\n| `OPENROUTER_API_KEY` | No* | OpenRouter API key — https://openrouter.ai/keys |\n| `GROQ_API_KEY` | No* | Groq API key — https://console.groq.com/keys |\n| `GOOGLE_API_KEY` | No* | Google AI Studio key — https://aistudio.google.com/apikey |\n| `DEEPSEEK_API_KEY` | No* | DeepSeek API key — https://platform.deepseek.com |\n| `MISTRAL_API_KEY` | No* | Mistral API key — https://console.mistral.ai |\n| `OLLAMA_HOST` | No | Ollama server URL (default: `http://localhost:11434/v1`) |\n| `LMSTUDIO_HOST` | No | LM Studio server URL (default: `http://localhost:1234/v1`) |\n| `LLAMACPP_HOST` | No | Llama.cpp server URL (default: `http://localhost:8080/v1`) |\n| `ALLOWED_DIR` | No | Directory for file operations (default: `./workspace`) |\n| `LOCAL_TIMEOUT` | No | Timeout (ms) for local model requests (default: 300000) |\n| `LOG_LEVEL` | No | Log level: `debug`, `info`, `warn`, `error` (default: `info`) |\n| `MAX_EXCHANGES` | No | Max user ↔ assistant exchanges kept in sliding window (default: `20`) |\n| `MAX_TOOL_RESULT_LENGTH` | No | Max chars before tool results are truncated (default: `5000`) |\n\n\\* At least one API key is required (not needed for local providers).\n\n## Large Projects\n\nFor medium-to-large projects, the default sliding window (20 exchanges) may drop older context. Increase these values in `.env`:\n\n```env\n# Keep up to 50 user-assistant exchanges\nMAX_EXCHANGES=50\n\n# Allow tool results up to 20,000 characters\nMAX_TOOL_RESULT_LENGTH=20000\n```\n\nYou can also reset the conversation mid-session with `/reset` if the model gets confused by stale context.\n\n## Limitations\n\n- **System prompt adherence**: Some free models (e.g., Nvidia Nemotron 550B) may ignore or partially follow system instructions. Switch to a different model if you notice this.\n- **Rate limits**: Free-tier API keys have daily rate limits (HTTP 429). The agent retries with exponential backoff (max 3 attempts), but persistent limits require switching providers or waiting.\n- **Token window**: With a 128K context model and 20-exchange sliding window, large codebases may hit context limits. Increase `MAX_EXCHANGES` and `MAX_TOOL_RESULT_LENGTH` in `.env` for larger projects.\n- **Stuck detection**: The agent stops after 3× identical tool calls or 5× consecutive same-name calls, injects a recovery system message, and removes the last tool results. Simply rephrase your request to continue.\n- **Windows shell**: PowerShell pipeline operators (`|`, `\u0026\u0026`) may trigger verbose permission prompts under strict opencode.json rules. Simple commands work without prompts.\n- **Relative vs absolute paths**: Models handle paths inconsistently — some use relative paths, others absolute. The agent normalizes paths within `ALLOWED_DIR`.\n\n## Security\n\n- All file operations restricted to `ALLOWED_DIR` — `sanitizePath` prevents traversal attacks\n- Shell commands run inside the workspace directory\n- API keys are stored in `.env` (listed in `.gitignore`, never committed)\n- Safe mode (`/safe`) restricts commands to a whitelist\n- Dangerous shell commands blocked by denylist (rm -rf, dd, mkfs, wget, etc.)\n- Use `local/` scripts for backup/restore\n\n## Contributing\n\nContributions are welcome! Feel free to open an [issue](https://github.com/maz557/coding-agent-free/issues) or submit a pull request. Star the repo if you find it useful — it helps others discover it.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaz557%2Fcoding-agent-free","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaz557%2Fcoding-agent-free","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaz557%2Fcoding-agent-free/lists"}