The-Agency/QUICK_START_REPL.md

Quick Start: Using the Dart CLI REPL

Setup

1. Install dependencies (for Flutter app parts)

flutter pub get

2. Set up API key

Choose one:

Option A: OpenRouter (vendor-neutral, recommended)

export OPENROUTER_API_KEY="sk-or-..."

Option B: Anthropic

export ANTHROPIC_API_KEY="sk-ant-..."

3. Start the REPL

dart lib/clawd_code.dart
# OR (if you have it installed as a CLI tool)
clawd_code

You'll see:

clawd_code 0.1.0
Dart CLI migration shell. Type /help for commands.
clawd>

---

Using the REPL

Free-form prompts (new functionality!)

Just type any question:

clawd> How do I create a web server in Go?

The model will respond and may use tools:

→ Calling Bash
← Bash returned: Created main.go with basic HTTP server...

To create a simple web server in Go, I've created a main.go file
with an HTTP server that listens on port 8080...

Commands (slash-prefixed)

clawd> /help                    # See all commands
clawd> /model                   # View/change model
clawd> /status                  # Show session status
clawd> /effort high             # Set effort level
clawd> /clear                   # Clear screen

Tool invocations (syntax: toolname: args)

clawd> bash: ls -la
clawd> read: /path/to/file
clawd> grep: pattern lib/src
clawd> glob: **/*.dart

Conversation history

Your conversation is maintained in memory during the session:

clawd> Write a function to reverse a string
<model responds with code>

clawd> Can you add error handling?
<model recalls previous code and improves it>

---

What Works

✅ Free-form prompts → Model processes them
✅ Model tool calls → Bash, file ops, search, etc. execute
✅ Streaming → See responses as they're generated
✅ Conversation history → Model remembers context
✅ Cost tracking → See how much you've spent
✅ Multiple vendors → Works with OpenRouter or Anthropic

---

What Doesn't Work Yet

❌ Real background tasks → /tasks stores metadata only, no execution
❌ Real MCP servers → /mcp is simulated
❌ Real agents → /agents is simulated
❌ Some commands → 25+ commands not yet ported

---

Environment Variables

Control behavior with these variables:

# API selection
export USE_OPENROUTER=true          # Prefer OpenRouter
export USE_ANTHROPIC=true          # Prefer Anthropic

# API keys
export OPENROUTER_API_KEY="..."
export ANTHROPIC_API_KEY="..."

# Model override (if not using /model command)
export CLAUDE_CODE_MODEL="gpt-4"    # OpenRouter model

# Debug
export CLAWD_DEBUG=true             # More verbose output

---

Troubleshooting

"No API key configured"

export OPENROUTER_API_KEY="your-key-here"
# OR
export ANTHROPIC_API_KEY="your-key-here"

"Base URL not configured"

This is the new vendor-neutral requirement. Set one of:

export OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_BASE_URL="https://api.anthropic.com/v1"
export CLAUDE_CODE_BASE_URL="https://your-backend.com/api/v1"

"Unknown model"

Set a valid model name:

/model claude-opus-4
# OR
/model openrouter/auto

Model is slow

Check your API key is valid and you have quota available.

Task not persisting

Tasks are saved to ~/.clawd_code/tasks/ as JSON files. Check that directory exists and is writable.

---

Examples

Example 1: Code generation

clawd> Write a Dart async function that fetches data from an API

<model responds with code, may call Bash to create a file>

Example 2: File editing

clawd> Read lib/src/app.dart and explain the main entry point

<model calls Read tool, then explains>

Example 3: Debugging

clawd> Search lib/ for all uses of BashTool

<model calls Grep, finds all references>

Example 4: Web research

clawd> Search for best practices for Dart CLI development

<model calls WebSearch tool if available, returns current info>

---

Cost Tracking

After each model call, you'll see:

$0.05 for this prompt (1,234 input + 456 output tokens)
Session total: $0.32

Costs saved to ~/.claude/last_session_cost.json on exit.

---

Next Steps

• Try /help to see all commands
• Try a free-form prompt about your codebase
• Use /tasks create to track work
• Use /config to see and change settings
• Use /theme to change appearance

---

Architecture Note

This REPL implementation:

• ✅ Is vendor-neutral (works with OpenRouter, Anthropic, or custom backend)
• ✅ Works without any backend (model API is external, not local)
• ✅ Maintains conversation history in memory
• ✅ Integrates with full tool system (permissions, telemetry, etc.)
• ❌ Does not require Flutter (pure Dart CLI)

For the full Dart CLI experience without Flutter deps, run:

dart lib/clawd_code.dart

For the Flutter app with UI, run:

flutter run

Both use the same underlying model integration.