tapes

OpenCode Setup

Capture every OpenCode conversation automatically by routing API calls through tapes.

Quick Start

The simplest way to capture OpenCode conversations:

tapes start opencode

On first run, tapes prompts you to select a provider:

Select a provider for opencode:
1) openai
2) ollama
Enter choice [1]: 1
Enter model [gpt-5.2-codex]:

Your selection is saved to ~/.tapes/config.toml for future sessions.

Specifying Provider via Flags

Skip the interactive prompt by specifying provider and model directly:

# Use OpenAI Codex
tapes start opencode --provider openai --model gpt-5.2-codex

# Use local Ollama models
tapes start opencode --provider ollama --model qwen3-coder:30b

What It Does

This automatically:

• Starts the tapes daemon with auto-selected ports
• Configures OpenCode to route the selected provider through the proxy
• Merges proxy settings with your existing OpenCode config
• Tags all conversations with agent_name: opencode
• Restores your original OpenCode config when you exit

Conversations are stored in ~/.tapes/tapes.sqlite by default.

Manual Setup

For more control over ports and configuration, use tapes serve:

1. Start tapes

tapes serve \
  --upstream "https://api.openai.com" \
  --proxy-listen "0.0.0.0:8080" \
  --sqlite "./tapes.sqlite"

2. Configure OpenCode

Create the OpenCode config directory if it doesn't exist:

mkdir -p ~/.config/opencode

Create or edit ~/.config/opencode/opencode.json:

{
  "provider": {
    "openai": {
      "options": {
        "baseURL": "http://localhost:8080"
      }
    }
  }
}

Restart OpenCode for the config to take effect.

3. Use OpenCode

Open OpenCode and select an OpenAI model. Start a conversation. All OpenAI API requests are now captured in ./tapes.sqlite

Verify It's Working

Before using OpenCode, verify the config is in place:

cat ~/.config/opencode/opencode.json

After sending a message, check that conversations are being captured:

curl http://localhost:8081/v1/stats

You should see node count increase with each message:

{
  "turn_count": 4,
  "root_count": 1,
  "session_count": 1
}

What You Get

• Full conversation history - Every message, tool call, and response
• Token usage tracking - Input/output tokens and cache hits per conversation
• Cost analysis - Track API spending across sessions
• Semantic search - Find past work by meaning (setup guide)

Query Your Data

List Conversations

curl http://localhost:8081/v1/sessions

View Specific Conversation

curl http://localhost:8081/v1/sessions/<hash>

Search Conversations

After enabling semantic search:

curl "http://localhost:8081/v1/search?q=how%20did%20I%20fix%20the%20auth%20bug"

Stop Using tapes

Remove the baseURL configuration from ~/.config/opencode/opencode.json:

{
  "provider": {
    "openai": {
      "options": {}
    }
  }
}

Or delete the entire config file:

rm ~/.config/opencode/opencode.json

Restart OpenCode. It now connects directly to OpenAI. Your captured data in ./tapes.sqlite is preserved.

Troubleshooting

OAuth Credential Override

Issue: Conversations not captured despite correct config

Cause: Stored OAuth credentials in ~/.local/share/opencode/auth.json silently override explicit provider configuration

Solution: When using tapes start opencode, tapes automatically patches the auth file to remove OAuth entries for managed providers (OpenAI, Anthropic) during the session and restores them when OpenCode exits.

For manual setup, remove the OAuth credentials:

# Check for OAuth credentials
ls ~/.local/share/opencode/auth.json

# Remove if it exists
rm ~/.local/share/opencode/auth.json

# Restart OpenCode and verify config is now active

Codex Requires Explicit Auth

Codex is the only harness that requires explicit authentication due to API limitations. Before starting Codex, store a service account key:

tapes auth openai
# Enter your service account key (sk-svcacct-...)

Then start Codex:

tapes start codex

Config Not Applied

Verify the config file exists and contains the correct baseURL:

cat ~/.config/opencode/opencode.json

Ensure you've restarted OpenCode after making config changes.

Port Already in Use

lsof -ti :8080 | xargs kill -9

Verify tapes is Running

curl http://localhost:8081/ping

Should return: "pong"

Other Agents & Providers

Anthropic (via Claude Code)

For Anthropic models, Claude Code is the recommended path:

tapes start claude

Anthropic is a managed provider — no additional auth configuration required.

Codex

Codex requires explicit authentication due to API limitations. Store a service account key first:

tapes auth openai
tapes start codex

Ollama (Local Models)

For local models via Ollama, see the Ollama setup guide. Configure OpenCode to use Ollama and tapes will capture conversations with local models.

Running Multiple Providers

Run separate tapes instances on different ports to capture multiple providers simultaneously. Each provider uses its own database file.

Next Steps

• Enable semantic search - Find conversations by meaning
• Set up agent skills - Search from within your workflow
• Explore the API - Full API reference

* Request support for additional providers at github.com/papercomputeco/tapes/issues