Autonomous, Free, Multi-Provider LLM Coding Agent CLI

Fixo CLI is a terminal-based autonomous coding assistant designed to execute complex programming tasks directly in your workspace. It writes implementation plans, edits code files, runs test suites, and iterates toward the goal. Tree-sitter is used today for shell-command parsing and LSP-fallback syntax checks; expanding it to the workspace symbol map is on the roadmap.

Fixo CLI ships with 13 direct providers built-in (OpenAI, Anthropic, Google, Groq, Mistral, Cohere, OpenRouter, NVIDIA, Cerebras, SambaNova, GitHub Models, xAI, Zen) — paste your own key for any of them. The optional FreeLLMAPI proxy backend is available as an opt-in convenience for users who want load-balanced failover across free-tier providers without managing individual keys.

Here is how Fixo CLI compares against other prominent terminal and editor-based coding agents:

¹ The multi-agent path is currently triggered by a keyword heuristic. An LLM-based complexity classifier is wired-but-dead in src/planner.ts and is being moved onto the live code path.

Fixo CLI separates concerns between code understanding (workspace indexer), task coordination (Planner), and execution (Agent).

sequenceDiagram
    autonumber
    actor User as Developer
    participant CLI as Fixo CLI
    participant Indexer as Workspace Indexer
    participant Planner as Plan Engine
    participant Agent as Autonomous Agent
    participant Proxy as FreeLLMAPI Proxy
    participant LLM as Provider (Groq/Gemini/NIM)

    User->>CLI: Request task (e.g. "Fix auth bug")
    CLI->>Indexer: Scan repository & build export map
    Indexer-->>CLI: Return repository structure summary
    CLI->>Planner: Propose implementation plan
    Planner->>Proxy: Fetch reasoning (smart routing)
    Proxy->>LLM: Try highest ranked provider
    LLM-->>Planner: Return initial plan
    Planner-->>User: Present plan for approval
    User->>CLI: Plan Approved!
    CLI->>Agent: Execute code changes
    loop Iterative Execution
        Agent->>Proxy: Request edit / test run
        Proxy->>LLM: Fallback routing (failover on error)
        LLM-->>Agent: Code output / Command to run
        Agent->>CLI: Apply file changes & execute tests
    end
    Agent-->>User: Task completed successfully!

Note on routing: Smart routing across models (cheaper for planning, stronger for execution) is a feature of the optional FreeLLMAPI proxy backend. In direct-provider mode, requests use the model you selected at setup — local fast/heavy-tier substitution via preferences.modelRouting is on the roadmap.

• Autonomous Agent Loop: Fixo CLI runs an agent loop that defines planning sub-agents, writes files, runs shell commands, reads compiler output, and self-corrects until tests pass.
• Workspace Indexer: Today, a depth-capped (4 levels, 200 files) directory scanner extracts exports via regex for a quick repository map. A tree-sitter-backed symbol map for TS/JS/Python/Go/Rust is on the roadmap; the WASM runtime is already vendored and used elsewhere in the codebase.
• Free Multi-Provider Routing: Connects to your FreeLLMAPI server to query models like Llama 3.3, Qwen 3, and Gemini 2.5/3.1 without incurring high API costs.
• Smart Cooldown & Failover: The CLI automatically tracks rate-limited providers (429/402/404) and switches to working alternatives in the fallback chain mid-request.
• Resilience Stack: Stream recovery, provider cooldown, context-budget enforcement, and a local telemetry sink work together so the agent stays productive on flaky networks and large codebases. See Resilience below.
• Built-in Workspace Guard: Safely manages workspace locks, preventing concurrent file writes and ensuring git safety.

The agent dispatches the following tools through the unified executeTool() entrypoint in src/agent/tool-executor.ts. Every call is gated by the granular permission engine (checkPermission) before any side effect runs. Mode indicates which execution modes the tool is callable from (PLAN, BUILD, EXPLORE, SCOUT); tools that mutate the workspace are blocked outside BUILD.

A token-aware predictive gate sits in front of read_file. Before the byte gate runs, the gate projects the file's token cost via gpt-tokenizer, adds the current conversation token count, and defers the read with a [Context-Budget Guard] directive if the projected total would exceed predictiveBudgetPct of the model's input window (default 0.85). The directive routes the model to extract_symbols / extract_imports / str_replace instead of reading the full file. Configurable via preferences.safety.predictiveBudgetPct — set to 1.0 to disable.

Fixo CLI is built for hostile environments: free-tier rate limits, dropped SSE streams, providers that 502 mid-response, and codebases larger than any single context window. The resilience stack is organised into four independent pillars, each of which can be tuned or disabled individually via ~/.fixocli/config.json.

All four pillars are controlled by the preferences.resilience block in your config. Every field has a safe default, so you can omit the entire block if you want the shipped behaviour.

{
  "preferences": {
    "telemetry": true,            // Master switch for *all* telemetry
    "telemetryLocal": true,       // Append events to ~/.fixocli/telemetry.jsonl
    "telemetryRemote": false,     // POST events to the FreeLLMAPI server (anonymous)
    "resilience": {
      "streamResume":       "auto",    // "auto" | "never"  (kill-switch for stream recovery)
      "maxResumeAttempts":  3,         // additional attempts after a mid-stream cut
      "useWithRetry":       true,      // use the withRetry engine for non-streaming calls
      "contextBudget":      "auto",    // "auto" | "truncate" | "never"  (kill-switch for budget enforcement)
      "contextBudgetRatio": 0.8        // fraction of model window used as the hard cap
    }
  }
}

After a session that didn't go well, run the diagnostic from the CLI:

fixo --diagnose

Or read the log directly:

tail -50 ~/.fixocli/telemetry.jsonl | jq .

diagnoseFailures() looks at the last hour by default and reports patterns such as:

• 3+ retries in the window → likely flaky network or rate-limit
• provider cooldown → at least one provider is rate-limiting; others are being preferred automatically
• stream-resume exhaustion → raise maxResumeAttempts or check your network
• repeated tool failures → the same tool has failed 3+ times; check its inputs
• 5+ provider errors → likely a provider outage

See docs/RESILIENCE.md for the pillar-by-pillar design notes.

The Resilience section above covers uptime (how Fixo stays alive through network noise). This section covers integrity — how Fixo protects the user's workspace and secrets. The two are deliberately orthogonal and live in separate configuration blocks:

The full schema lives under preferences.safety in ~/.fixocli/config.json. Defaults are safe for interactive use; tighten them for CI / unattended runs.

{
  "preferences": {
    "safety": {
      "atomicStaging":     true,
      "stagingTtlMs":      86400000,
      "lspPreSave":        "warn",
      "loopTrap": {
        "triggerCount":        3,
        "hardAbortCount":      6,
        "toolResultTailBytes": 1024,
        "maxHistory":          64,
        "enabled":             true
      }
    }
  }
}

Two detectors run in parallel:

• Composite (LoopTrapDetector) — fingerprints the tool call arguments and the tail of the tool result and trips when three consecutive turns hash to the same value. Defends against a deterministic "stare at one line" loop.
• Semantic (SemanticLoopDetector) — fingerprints the target file path of every file-mutating tool and trips when the same path appears three times inside a sliding 5-turn window. Defends against an LLM that varies its search arguments (different line numbers, different patterns) but keeps hammering the same file.

On triggerCount the detector injects a [Safety-Alert] directive into the next system prompt. On hardAbortCount it throws SemanticLoopAbortedError, which the agent catches and translates into a clean AtomicStagingManager.rollbackAll() so no half-edited file survives.

read_file is gated by both a byte threshold (largeFileGateBytes, default 15 KiB) and a line threshold (largeFileGateLines, default 350). When a file exceeds either, the LLM receives a synthetic [Context-Budget Guard] directive that points it at the new structural pre-scan tools:

• extract_symbols(path) — top-level declarations only (cap 100 per file).
• extract_imports(path) — dependency list only (cap 100 per file).

Each pre-scan call records the result in the TaskSession.structuralMaps map so the LLM's later reads can prove they were narrowed first.

When no language server (typescript-language-server, gopls, rust-analyzer, …) is on the PATH, the pre-save gate falls back to syntaxHealthCheck — a pure-JS brace/paren/bracket balance check that runs in microseconds. Set FIXO_LSP_FALLBACK=syntax-only to force the fallback even when a real LSP is available (useful for sandboxed CI). The boot sequence also surfaces a one-time warning when neither is present.

src/runtime/redaction.ts exposes three helpers for the three distinct places redaction is needed:

• stripAnsi(value) — drop every ANSI escape entirely. Use for content piped into another tool that doesn't care about colour.
• redactAnsi(value) — replace the \x1b byte with the printable form \\x1b so the message survives a log write / telemetry upload without injecting control codes downstream. Use for content whose bytes must be preserved (file paths, error messages).
• scrubForLlm(value) — strip ANSI and replace every recognised secret pattern with [REDACTED]. This is the only safe redaction for content heading back into a model prompt.

The staging pipeline writes to <cwd>/.fixo/staging/<runId>/ and would silently bloat the disk if entries were never cleaned up. Two sweeps run automatically:

• Per-run GC — AtomicStagingManager.gc() removes entries older than stagingTtlMs from the current run's directory.
• Global GC — AtomicStagingManager.garbageCollectAll(cwd, ttlMs) sweeps every <runId>/ directory. Invoked at the start of every runStreaming lifecycle (typically < 2 ms) and also exposed via the /fixo gc slash command for power users.

GC is bounded and uses the metadata createdAt timestamp rather than file mtime, so the TTL is a deterministic policy decision rather than a side effect of kernel flush timing.

The [Loop-Trap] directive is injected into the system prompt after 3 consecutive equivalent turns. The model is expected to reconsider its strategy. If it doesn't, the detector hard- aborts at 6 turns and the session terminates with LoopTrapAbortedError.

Diagnosis:

tail -100 ~/.fixocli/telemetry.jsonl | jq 'select(.event == "loopTrap")'

Fix:

1. Read the directive — it tells the LLM why the loop is happening. Common causes:
   • The test command is failing consistently → fix the test.
   • The patch is being reverted by a pre-commit hook → fix the hook.
   • The agent is confused about file paths → clarify the task.
2. Force a manual compaction to drop the noise from the conversation history:

   fixo --compact

3. To disable the detector for a single session (debugging only), set loopTrap.enabled to false in ~/.fixocli/config.json.

write_file returns Error: Pre-commit hook rejected: LSP pre-save blocked: N error(s) in <path> — <line>:<col> <message>; ...

Diagnosis:

1. The first 3 error messages in the string are the gate's best guess at the root cause.
2. Open the file in your editor — the LSP (if installed) underlines the offending line.
3. Common causes:
   • Missing import → add it.
   • Type mismatch → fix the annotation.
   • Reference to an undeclared identifier → typo.

The original file is preserved on every blocked write. Re-run the agent's suggested fix and try again.

If the gate is over-firing (a known-good write is being rejected), lower the mode from block to warn:

{ "preferences": { "safety": { "lspPreSave": "warn" } } }

The agent said it wrote a file, but the file is unchanged.

Diagnosis:

1. Check the tool result string for PreCommitHookRejectedError or StagingPathEscapeError.
2. For PreCommitHookRejectedError, the cause field is the underlying error (LspPreSaveBlockedError, or a future pre-commit hook). Read cause.message.
3. For StagingPathEscapeError, the target path escapes the workspace root — this is a caller bug. Reject and re-prompt.

du -sh ~/.fixo/staging

Fix:

1. The auto-GC runs at the start of every runStreaming cycle. If the directory is large during a session, an LLM is staging writes but failing to commit them. Inspect the session log for PreCommitHookRejectedError.
2. Manual sweep (safe; staging is ephemeral):

   rm -rf ~/.fixo/staging/*

3. Lower stagingTtlMs to expire entries sooner:

   { "preferences": { "safety": { "stagingTtlMs": 3600000 } } }

fixo providers list
fixo providers add openai sk-proj-...

The vault is auto-hydrated on the next getDirectConfig call, so the new key is visible immediately — no restart required.

Security note: never paste a real key into a chat message, a GitHub issue, or a tool result. scrubForLlm redacts common shapes, but a low-entropy prefix is not guaranteed to match.

# Drop the staging directory (ephemeral)
rm -rf ~/.fixo/staging

# Drop the cached vault singleton (next call re-hydrates)
fixo providers reset-vault

# Reset to safe production defaults
fixo config reset --section safety

See docs/SAFETY.md for the full threat model, design notes, and operator reference.

The Dashboard (src/ui/render.ts) is a typed event bus that the agent and any number of subscribers (UI, telemetry, tests) can wire into without coupling:

• Dashboard is a pure state holder. It never touches stdout.
• DashboardSubscriber is a one-method interface; errors thrown by a subscriber are counted in Dashboard.subscriberErrors and never propagate.
• The default AnsiRenderer paints a double-buffered surface to the terminal and chooses one of three render modes:
  • off — non-TTY (CI, captured pipes). Nothing is written.
  • single-line — terminals below 80×24.
  • dashboard — full multi-line surface.

Wiring an additional subscriber is one line:

import { dashboard, AnsiRenderer } from './ui/render.js';
const renderer = new AnsiRenderer();
dashboard.subscribe(renderer);

The agent emits turn-start, tool-start, tool-finish, tokens, status, log, mode, and done events. Each event is a tagged union so refactors stay type-safe.

Ensure you have Node.js (v18+) and npm installed. Fixo CLI connects to FreeLLMAPI, so you should have a running FreeLLMAPI server or access to a unified proxy endpoint.

Clone the repository and install dependencies:

git clone https://github.com/Abrar-Akhunji/FIXO_CLI.git
cd FIXO_CLI
npm install

Compile the TypeScript code:

npm run build

Create a .env file at the root of your project:

# URL of your FreeLLMAPI instance
FREELLMAPI_URL=http://localhost:3001
# Your unified API key (retrieve from FreeLLMAPI Dashboard)
FREELLMAPI_KEY=your-unified-api-key-here

Start Fixo CLI in dev mode or link it globally:

# Run directly
npm run dev

# Or link globally to run 'fixo' from anywhere
npm link
fixo

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.