Mirage Code Agent

A Claude-powered code agent backed by Mirage — a unified virtual filesystem that mounts disk, RAM, S3, GitHub, Google Drive, and 20+ other backends into a single filesystem tree.

Architecture

User Task
    │
    ▼
MirageCodeAgent  (claude-opus-4-7 + adaptive thinking)
    │
    ├── list_directory  →  Workspace.ls()
    ├── read_file       →  Workspace.cat()
    ├── write_file      →  Workspace.write() / DiskResource
    ├── search_code     →  grep across mounted filesystem
    ├── find_files      →  find across mounted filesystem
    └── run_bash        →  shell commands in workspace cwd

The agent mounts your target directory as a DiskResource (or RAM via RAMResource) and exposes all file operations as Claude tools. Claude orchestrates the coding task by exploring, reading, writing, and verifying files through the Mirage workspace.

Setup

git clone git@github.com:JayKimProject/mirage-code-agent.git
cd mirage-code-agent
pip install -r requirements.txt
cp .env.example .env
# Add your ANTHROPIC_API_KEY to .env

Mirage requires Python 3.12+. Install it from source if needed:

git clone git@github.com:JayKimProject/mirage.git
cd mirage/python && uv sync --all-extras --no-extra camel
pip install -e .

Usage

# Point the agent at an existing project
python main.py --workspace ./my-project --task "add type hints to all functions"

# Write and run tests
python main.py --workspace ./my-project --task "write unit tests for utils.py and run them"

# Refactor
python main.py --workspace ./my-project --task "refactor the auth module to use dataclasses"

# In-memory workspace — nothing touches disk, all files live in Mirage RAM
python main.py --memory --task "create a fibonacci module with pytest tests"

# Quiet mode — suppress tool logs, print only final response
python main.py --workspace ./my-project --task "fix all type errors" --quiet

Sample Output

════════════════════════════════════════════════════════════
  MIRAGE CODE AGENT
════════════════════════════════════════════════════════════
  Workspace : /Users/jay/my-project
  Task      : add type hints to all functions
════════════════════════════════════════════════════════════

  [list_directory] {"path": "/workspace"}
    → ["src", "tests", "README.md", "pyproject.toml"]
  [find_files] {"pattern": "*.py", "path": "/workspace"}
    → ["/workspace/src/utils.py", "/workspace/src/auth.py", ...]
  [read_file] {"path": "/workspace/src/utils.py"}
  [write_file] {"path": "/workspace/src/utils.py", "content": "..."}
  [run_bash] {"command": "mypy src/"}
    → [exit code: 0]

╔══════════════════════════════════════════════════════════════════════╗
║                          AGENT RESULT                                ║
╚══════════════════════════════════════════════════════════════════════╝

Added type hints to 3 files: utils.py, auth.py, models.py.
All mypy checks pass with exit code 0.

Workspace Modes

Mode	Backend	Use Case
--workspace PATH	DiskResource	Edit real files on disk
--memory	RAMResource	Ephemeral sandbox, nothing persisted

Project Structure

mirage-code-agent/
├── main.py          # CLI entry point
├── agent.py         # MirageCodeAgent: tools + agentic loop
├── requirements.txt
└── .env.example

Claude API Features Used

Feature	Where
claude-opus-4-7	Agent model
Adaptive thinking	Agent reasoning
Tool use (manual loop)	All 6 filesystem tools
Prompt caching	System prompt

Requirements

• Python 3.12+
• anthropic >= 0.40.0
• mirage-ai >= 0.1.0
• python-dotenv >= 1.0.0