Open source CLI tool that drives AI coding assistants via browser automation
FreeCode is a thin-client CLI that drives AI coding assistants (ChatGPT, Claude, Gemini) via browser automation to assist with coding tasks. The architecture uses a two-phase approach: the AI first returns which files it needs, then receives those files with the prompt and returns structured file changes.
- TUI + VS Code Extension — Choose your interface
- JSON-RPC over stdin/stdout — Lightweight IPC between frontends and CLI
- Browser-based AI providers — Direct integration with ChatGPT, Claude, Gemini
- Two-phase context collection — Efficient file retrieval before prompts
- Diff preview before apply — Review changes before writing
- Persistent CLI daemon — Reuses browser connection across turns
| Tool | Description | Parameters |
|---|---|---|
read |
Read file or directory contents | filePath, offset?, limit? |
write |
Create or overwrite files | filePath, content |
edit |
Edit files in-place with smart matching | filePath, oldString, newString, replaceAll? |
glob |
Find files matching glob patterns | pattern, path? |
grep |
Search file contents via regex | pattern, path?, include?, -n?, -i?, -C? |
bash |
Execute shell commands | command, timeout?, workdir? |
skill |
Load specialized skills from SKILL.md | name |
question |
Ask user clarifying questions | questions (JSON array) |
| Mode | Tools | Behavior |
|---|---|---|
| Sequential | edit, write |
One at a time, in order |
| Parallel-safe | read, glob, grep |
Batch concurrently |
Skills are specialized instruction sets loaded from SKILL.md files. They provide structured workflows for specific tasks.
Skill locations:
~/.claude/skills/— Global skills~/.agents/skills/— Agent skills.claude/skills/— Project skills.freecode/skills/— Project skills
Example skill structure:
# .freecode/skills/brainstorming/SKILL.md
---
name: brainstorming
description: Explore requirements before building features
---
# Brainstorming Skill
1. Clarify the goal - what problem are we solving?
2. Identify constraints - what must/must not happen?
3. Explore alternatives - what approaches exist?
4. Define success - how do we know it's done?# Install dependencies
npm install
# Start the TUI
cd apps/tui && npm run dev┌─────────────────────────────────────────────────────────────┐
│ TUI │
│ (apps/tui) — pure UI shell │
│ Uses pi-tui for terminal rendering │
│ IPC client sends/receives JSON-RPC │
└──────────────────────────┬──────────────────────────────────┘
│
│ JSON-RPC (stdin/stdout)
▼
┌─────────────────────────────────────────────────────────────┐
│ CLI Backend │
│ (apps/core) — ALL intelligence │
│ Browser controller, parser, tools, context engine, │
│ agent loop, file applier │
└──────────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ AI Provider (Browser) │
│ ChatGPT / Claude / Gemini │
└─────────────────────────────────────────────────────────────┘
MIT