← Portfolio/free-code

free-code

Every capability, explained.

Code Graph — Symbol index & navigation

Local structural index of your entire codebase. No cloud. No upload. Sub-second lookups.

The code graph indexes every TypeScript, JavaScript, Python, and Java file in your project, building a queryable map of symbols (functions, classes, methods, interfaces, types, enums) and the call edges between them. The result is stored in .code-graph/ at the project root — a set of JSON files the agent reads in milliseconds.

What this means in practice

  • The agent never has to read a 2,000-line file to find a 10-line function.
  • It can answer "who calls parseArgs?" across 500 files instantly.
  • It sees the exact call tree: which functions a symbol delegates to.
  • Incremental re-indexing — only changed files are re-parsed.

Four agent tools

ToolWhat it does
code_index Build or incrementally update the index. Runs automatically when stale.
code_symbols Case-insensitive substring search by name or qualified name, with optional kind filter.
code_callers Returns every call site that invokes a named function or method, with file and line.
code_context Full source of a symbol plus its direct callees. Validates freshness against the index.

Stale index detection

On every session startup, free-code checks whether any indexed source files (.ts / .js / .py / .java and friends) have been modified since the last index run. If they have, it displays a warning and suggests running code_index before using the other tools.

Tip
Run /codeGraph-index once after cloning a repo, then /codeGraph-index --force after large refactors. Day-to-day incremental updates happen automatically.

Full code graph documentation →

RAG — Local knowledge base

Add any document as permanent project context. Vector search, no cloud required.

The RAG (Retrieval-Augmented Generation) extension provides a local vector knowledge base served on port 8085. Index documentation, runbooks, architecture notes, or any text file. The agent retrieves the most relevant chunks automatically during a session.

Start the server

The knowledge base is served by a small local server (default port 8085). Start it, then create and select a knowledge base:

# 1. Start the RAG server (keep it running)
free-code-rag            # default http://localhost:8085

# 2. In a free-code session, create and select a knowledge base
/rag-kb create my-docs
/rag-kb use my-docs

# 3. Add documents
/rag addFile ./README.md

Key commands

CommandDescription
/rag addFile <path>Index a single document
/rag addGroup <folder>Index all supported files in a folder
/rag addGithubUrl <url> [subpath]Clone a GitHub repo and index its files. Optionally target a subdirectory. Source is saved to sources.json for future refreshes.
/rag search <query>Query the knowledge base and inject as context
/rag listList all indexed documents
/rag remove <file>Remove a document from the index
/rag refreshRe-fetch and re-index all sources registered via addFile and addGithubUrl
/rag schedule [daily|weekly]Set up automatic recurring refresh (requires at least one GitHub source)
/rag-kb create <name>Create a named knowledge base
/rag-kb use <name>Switch the active knowledge base
/rag-kb listList all knowledge bases
Use case
Index your team's ADRs, internal API docs, or a third-party library's documentation. The agent will cite from your knowledge base instead of hallucinating about it.

Browser automation

The agent controls a real browser. No Selenium. No mocks.

free-code ships with a built-in browser tool backed by Chrome DevTools Protocol (CDP). The agent can navigate pages, click, fill forms, take screenshots, and extract structured content — treating web UIs like any other tool.

Browser commands

Command / toolDescription
/browse [url] [goal]Open a URL in the visible browser and describe the goal
agent_browser toolFull programmatic control: navigate, screenshot, interact
/gemini ask <message>Send a message to Gemini via browser CDP flow
/gemini download <file>Download a Gemini-generated artifact
/gemini open [chat_id]Open a Gemini conversation in the browser
Use case
Ask the agent to research a competitor's API, scrape documentation that has no official download, or walk through a multi-step web form on your behalf.

Watch: Browser automation

MCP Servers — Unlimited extensibility

Connect any Model Context Protocol server and its tools appear automatically.

Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and services. free-code supports any MCP-compatible server: databases, APIs, design tools, monitoring dashboards, CI systems — if it speaks MCP, it works.

Adding an MCP server

/mcp-import                     # guided import from a URL or file
# or edit directly:
~/.free-code/agent/mcp.json

After import, restart the session. The new tools appear in the agent's tool list automatically — no code changes required.

Examples
Connect a Postgres MCP server to let the agent query your database. Add a Figma MCP to read design tokens. Wire up a GitHub MCP to manage PRs and issues.

Security — Layered guardrails for the agent

Audit sessions, approve risky actions, and control what the agent can reach — locally or in the cloud.

free-code is built for environments where an agent has real power over files, shells, and external systems. Security is not a single switch: it is a stack of visibility, policy, and user confirmation you can tune for your team.

Report and export conversations

Every session is persisted under ~/.free-code/. Export or share transcripts for review, compliance, or handoff:

CommandUse
/export [file]HTML, Markdown, or JSONL archive of the session
/shareUpload as a private GitHub gist and get a link
/sessionPath, token usage, and cost for the active session

Damage-Control — bash and file firewall

The bundled Damage-Control extension enforces YAML rules before the agent runs bash commands or touches sensitive paths. Dangerous patterns (for example rm -rf / or piping curl into bash) can be blocked or require an explicit confirmation dialog in real time — so the user decides before a potentially harmful command runs.

  • Bash patterns — regex rules with a human-readable reason
  • Path policies — zero-access, read-only, and no-delete paths
  • MCP authorization — first MCP tool call per session prompts allow/deny for the rest of the session
  • Audit log — blocks and denials are recorded in the session as damage-control-log entries
# Toggle enforcement for the current session
/damage-control [on|off|toggle|status]

# Customize rules (copy the sample next to your extension, or edit the bundled file)
damage-control-rules.yaml

Sample rules ship with the agent (blocking ~/.ssh/, /etc/, and common destructive bash idioms). Teams can extend the file for their own policies.

Visibility — skills, MCP, and agents in use

Before trusting what the agent can do, you need to see what is loaded on the machine:

  • /tools and /commands — active tools and slash commands for this session
  • /reload — refresh extensions, skills, prompts, and context files after install changes
  • Session monitor (VS Code / Cursor plugin and macOS app) — live counts of messages, tool calls, MCP tools, skills, and subagents, plus context usage
  • ~/.free-code/agent/mcp.json — MCP servers configured for the user

This makes it clear which external systems (Jira, GitHub, databases, etc.) the agent can reach through MCP, and which reusable skills shape its behavior.

Local-first with cloud deployment

Run entirely on a developer laptop with local or API-based models. When your organization requires it, use the same agent with cloud LLM providers (Anthropic, Vertex, OpenAI-compatible endpoints) or host sessions in managed environments — always with the same Damage-Control and MCP policies available in the CLI, plugin, and macOS app.

Tip
Start with the bundled damage-control-rules.yaml, turn enforcement on with /damage-control on, and export a test session with /export to validate your audit workflow before rolling out to the team.

Subagents — Multi-agent workflows

Delegate tasks to parallel agents from within a single session.

A subagent is a full agent session running alongside your main session. Spin up as many as you need. Each has its own context window, tool access, and conversation thread. Coordinate them to work on independent subtasks in parallel.

CommandDescription
/sub <task>Start a new subagent with a task description
/subcont <n> <prompt>Continue talking to subagent #n
/subrm <n>Remove subagent #n
/subclearClear all subagent widgets
Use case
Run a security audit in one subagent while a second writes tests and a third drafts the changelog. All three run in parallel, each with full tool access.

Project context files

Drop a file at the repo root and the agent picks it up automatically — no configuration needed.

On every session start, free-code walks the project directory and its parents looking for context files. Any file it finds is injected into the agent's system prompt, giving the agent standing instructions specific to that project.

Supported filenames (in discovery order):

FileTypical use
FREE_CODE.mdfree-code-specific project guidance (architecture notes, agent workflow rules, file conventions)
CLAUDE.mdCompatible with Claude Code projects — same file, picked up automatically
AGENTS.mdCompatible with OpenAI Codex / other agent tooling that uses this convention

What to put in a context file

  • Architecture decisions the agent should be aware of
  • Coding conventions and style rules for the project
  • Which commands to run before committing (npm run check, etc.)
  • Agent workflow rules (e.g. use subagents for broad exploration, always update web-docs/ alongside docs/)
  • Paths the agent should not touch
Compatibility
If your team already uses CLAUDE.md for Claude Code or AGENTS.md for another tool, free-code reads those files as-is. No migration needed.

Skills & Extensions — Reusable agent behaviors

Commit domain knowledge alongside your code. Share workflows with your team.

Skills are markdown files with YAML frontmatter. They inject instructions, context, and personality into the agent for a specific task. A skill can describe how to run your CI pipeline, how to write commit messages, or how to follow your team's code review guidelines. 

---
name: code-review
description: Follow our team's code review conventions
---
When reviewing code, always check for...

Extensions are TypeScript modules that add new tools, slash commands, and integrations. Extensions are auto-discovered from ~/.free-code/agent/extensions/ and loaded on every session start.

Install a package

free-code install npm:@scope/package       # from npm
free-code install git:github.com/org/pkg   # from a git repo
free-code install https://example.com/pkg  # from a URL
Tip
Skills are version-controlled markdown files. Ship them in your monorepo and every engineer on the team gets the same agent behavior automatically.

Multi-provider AI

One agent, every model. Switch without changing your workflow.

free-code is model-agnostic. Configure as many providers as you need. Cycle your curated shortlist with a single key binding. Switch to a different model mid-session at any time.

Built-in providers (Anthropic, OpenAI, Google, and more) appear in /model once you authenticate, and you can add any OpenAI-compatible endpoint or curate exactly which models show — all from ~/.free-code/agent/models.json. See the Models tab → for the full provider list and the only whitelist.

Switching models

  • Ctrl+L — open model selector
  • Ctrl+P / Shift+Ctrl+P — cycle your scoped shortlist forward / backward
  • /model — switch via command
  • Shift+Tab — cycle reasoning level (off → minimal → low → medium → high → xhigh)

Session management

Sessions that survive context limits, restarts, and long pauses.

Command / flagDescription
/resumeBrowse and pick a previous session
/forkBranch the current session into a new independent one
/compact [instructions]Summarize context to free up the context window
/treeNavigate session history as a branching tree; jump to any checkpoint
/name <name>Give the session a human-readable name
/export [file]Export to HTML, Markdown (.md), or JSONL
/shareUpload as a private GitHub gist and get a link
free-code -cCLI: continue the most recent session
free-code --fork <id>CLI: fork a specific session
free-code --no-sessionCLI: ephemeral mode, nothing is saved

Full command reference →  ·  Code graph →  ·  Product qualities  ·  Installation →

Developed by Pablo Castañeda