Onetimesecret MCP

🚀 Amp CLI Bridge - File-Based Communication System

The Amp CLI Bridge is a file-based message queue system. It allows Claude Code to utilize Amp CLI capabilities without using Claude Code credits. This system enables sending research requests, code analysis tasks, and other prompts to Amp CLI from Claude Code, with results returned asynchronously through a file-based queue.

🚀 Quick Start

1. Start the Watcher

In a separate terminal, run:

./scripts/amp/start-amp-watcher.sh

This initiates the background watcher process that monitors prompts/pending/ for new files.

2. Use from Claude Code

In your Claude Code session:

You: "Use @agent-amp-bridge to research TypeScript 5.0 features"

The agent will:

1. Create a prompt file in prompts/pending/
2. Wait for the watcher to process it
3. Read the response from responses/ready/
4. Present the results to you

3. Stop the Watcher

When finished:

./scripts/amp/stop-amp-watcher.sh

✨ Features

• Zero Claude Code Credits: All Amp API calls are made from a separate authenticated session.
• Async Processing: Claude Code doesn't block while waiting for responses.
• Fault Tolerant: The file-based queue can survive crashes and restarts.
• Audit Trail: All prompts and responses are saved for debugging and review.
• Reusable: Prompts can be replayed, and past responses can be reviewed.

📦 Installation

Setup (One-Time)

If this directory doesn't exist or is incomplete, create it:

# From project root
mkdir -p .claude/amp/prompts/pending
mkdir -p .claude/amp/responses/{ready,consumed}

Note: This directory is gitignored (user-specific working space). The structure is created locally as needed.

💻 Usage Examples

Using the Amp CLI Bridge in Claude Code:

You: "Use @agent-amp-bridge to research TypeScript 5.0 features"

📚 Documentation

Overview

The Amp CLI Bridge enables you to send various prompts to Amp CLI from Claude Code, and the results are returned asynchronously via a file-based queue.

Architecture

Claude Code (@agent-amp-bridge)
    ↓
    writes prompt to → prompts/pending/{uuid}.json
                              ↓
                    amp-watcher.js (separate process)
                              ↓
                    executes → amp -x "prompt"
                              ↓
                    writes → responses/ready/{uuid}.json
                              ↓
    Claude Code reads ← response

Directory Structure

.claude/amp/
├── prompts/
│   ├── pending/        # Queue for new prompts (watched by amp-watcher.js)
│   └── processed/      # Archive of completed prompts
├── responses/
│   ├── ready/          # Responses from Amp (read by Claude Code)
│   └── consumed/       # Archive of consumed responses
├── amp-watcher.js      # Node.js file watcher that processes prompts
├── config.json         # Configuration file
├── amp-watcher.log     # Watcher logs
└── README.md           # This file

Configuration

Edit .claude/amp/config.json:

{
  "pollInterval": 1000,      // Check for new prompts every 1s
  "timeout": 300000,          // 5 minute timeout per prompt
  "debug": false,             // Enable debug logging
  "ampCommand": "amp"         // Amp CLI command path
}

Message Format

Prompt File

Location: prompts/pending/{uuid}.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-11-04T20:00:00.000Z",
  "prompt": "Your research question or task here",
  "context": {
    "project": "mcp-memory-service",
    "cwd": "/path/to/project",
    "tags": ["research", "typescript"]
  },
  "options": {
    "timeout": 300000,
    "format": "markdown"
  }
}

Response File

Location: responses/ready/{uuid}.json

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-11-04T20:05:00.000Z",
  "success": true,
  "output": "Amp CLI response content here...",
  "error": null,
  "duration": 300000,
  "originalPrompt": { /* echo of prompt for reference */ }
}

Helper Scripts

Located in scripts/amp/:

• start-amp-watcher.sh - Start the watcher in the background
• stop-amp-watcher.sh - Stop the watcher gracefully
• test-amp-bridge.sh - Integration test (creates a test prompt, waits for a response)

Use Cases

• Web Research: "Research latest React 18 features and concurrent rendering"
• Code Analysis: "Analyze the storage backend architecture in src/storage/"
• Documentation: "Generate comprehensive API docs for MCP tools"
• Code Generation: "Create TypeScript type definitions for the API"
• Best Practices: "Find OAuth 2.1 security recommendations and implementation patterns"

Limitations

• Latency: File polling adds approximately 1s of overhead per request.
• Amp Credits: The system still consumes Amp API credits (free tier limits apply).
• Manual Start: The watcher must be started manually in a separate terminal.
• Best for Research: It is optimized for async research tasks, not real-time interaction.

🔧 Technical Details

Watcher Implementation

The amp-watcher.js script:

1. Polls prompts/pending/ every 1 second (configurable).
2. For each .json file found:
   • Reads the prompt.
   • Executes amp -x "{prompt}".
   • Captures stdout/stderr.
   • Writes the response to responses/ready/.
   • Moves the prompt to prompts/processed/.
3. Handles errors gracefully (writes error responses).
4. Supports graceful shutdown (SIGTERM/SIGINT).

Agent Implementation

The @agent-amp-bridge Claude Code agent:

1. Generates a UUID for request tracking.
2. Writes the prompt JSON to prompts/pending/.
3. Polls responses/ready/ for a matching UUID.
4. Reads and parses the response when available.
5. Moves the response to responses/consumed/.
6. Presents the formatted output to the user.

File Cleanup

Archives are kept for debugging:

• prompts/processed/ - Completed prompts
• responses/consumed/ - Consumed responses

Manual cleanup (optional):

# Remove archives older than 7 days
find .claude/amp/prompts/processed -name "*.json" -mtime +7 -delete
find .claude/amp/responses/consumed -name "*.json" -mtime +7 -delete

For Developers

Extending the System

Custom timeout per request:

{
  "prompt": "Complex analysis task",
  "options": {
    "timeout": 600000  // 10 minutes
  }
}

Debug mode:

node .claude/amp/amp-watcher.js --debug

Custom poll interval:

node .claude/amp/amp-watcher.js --interval 500  // 500ms

Testing Changes

1. Make changes to amp-watcher.js or the agent.
2. Restart the watcher: ./scripts/amp/stop-amp-watcher.sh && ./scripts/amp/start-amp-watcher.sh
3. Run the integration test: ./scripts/amp/test-amp-bridge.sh

Support

• Documentation: See CLAUDE.md section "Amp CLI Bridge"
• Issues: File at https://github.com/doobidoo/mcp-memory-service/issues
• Amp CLI Docs: https://ampcode.com/manual