Glass-Box Transparency

Unlike black-box solutions, Anvil follows a “glass-box” philosophy. Every piece of generated code is:

Visible - Saved as plain Python files
Editable - You can modify the code directly
Controllable - “Eject” tools to take full ownership

Viewing Generated Code

Via Filesystem

All tools are saved to your anvil_tools/ directory:

ls anvil_tools/
# __init__.py
# tool_registry.json
# search_notion.py
# get_weather.py

View any tool’s code:

cat anvil_tools/search_notion.py

Via CLI

List all tools with their status:

anvil list

Output:

📦 Anvil Tools (3 total)

  ● search_notion (v1.0)
      Search a Notion workspace for pages matching a query

  ● get_weather (v1.2)
      Get current weather for a city

  ○ custom_tool (v1.0) [ejected]
      Custom implementation

Via API

# Get tool code
code = anvil.get_tool_code("search_notion")
print(code)

# Get tool metadata
info = anvil.get_tool_info("search_notion")
print(info)

Editing Tools

You can edit any generated tool directly:

# ---
# ANVIL-MANAGED: true
# INTENT-HASH: abc123...
# VERSION: 1.0
# ---

def run(query: str) -> dict:
    # Add your custom logic here
    import requests
    response = requests.post(...)
    return response.json()

What Happens When You Edit

If you edit a tool and the ANVIL-MANAGED: true header is still present:

Anvil will overwrite your changes if the intent changes
Self-healing will replace your code on failure

To prevent this, eject the tool.

Ejecting Tools

“Ejecting” means taking full ownership of a tool. Anvil will never modify an ejected tool.

Method 1: Edit the Header

Change ANVIL-MANAGED: true to false:

# ---
# ANVIL-MANAGED: false
# INTENT-HASH: abc123...
# ---

def run(query: str) -> dict:
    # Your custom implementation
    ...

Method 2: Remove the Header

Tools without a header are treated as ejected:

# No header = ejected
def run(query: str) -> dict:
    # Your custom implementation
    ...

Ejected Tool Behavior

Feature	Managed Tool	Ejected Tool
Regeneration on intent change	✓	✗
Self-healing	✓	✗
Execution	✓	✓
Framework adapters	✓	✓

Ejected tools still work with all Anvil features except automatic code modification.

Tool Registry

Metadata for all tools is stored in tool_registry.json:

{
  "search_notion": {
    "name": "search_notion",
    "intent": "Search a Notion workspace",
    "docs_url": "https://developers.notion.com/...",
    "hash": "abc123...",
    "version": "1.0",
    "status": "active",
    "created_at": "2025-01-18T10:00:00Z",
    "last_generated": "2025-01-18T10:00:00Z",
    "error_count": 0
  }
}

Status Values

Status	Meaning
`active`	Tool is working normally
`failed`	Last execution failed
`ejected`	User has taken ownership

Version Control

All generated code is plain text and should be committed to git:

git add anvil_tools/
git commit -m "Add search_notion tool"

Recommended .gitignore

Anvil’s init command creates a proper .gitignore:

# Protect API keys
.env

# Python cache
__pycache__/
*.pyc

# Optional: Ignore generated tools (if you prefer not to commit them)
# anvil_tools/

Cleaning the Cache

To force regeneration of all tools:

# Remove all managed tools (keeps ejected)
anvil clean

# Remove all tools including ejected
anvil clean --force

# Keep ejected tools explicitly
anvil clean --keep-ejected

Benefits of Glass-Box

Debugging

When something goes wrong, you can inspect the exact code that ran:

# Check what Anvil generated
print(anvil.get_tool_code("broken_tool"))

Auditing

For compliance or security review, all code is visible:

# Review all generated code
for f in anvil_tools/*.py; do
    echo "=== $f ==="
    cat "$f"
done

Learning

See how the LLM solves problems:

# Compare different versions
diff anvil_tools/search_v1.py anvil_tools/search_v2.py

Customization

Start with generated code, then customize:

Generate initial tool
Test and verify it works
Eject and add custom logic
Commit to version control