myworkspace/docs/agent-tools-installation.md

Agent Tools Installation Guide

This guide covers installation and configuration of the multi-agent tooling stack for your MyWorkspace projects.

Overview

The tooling stack provides complementary agents for different workflow patterns:

Agent	Primary Use Case	Best For
OpenCode	Main autonomous agent	Test harness iteration, debugging loops, multi-file refactors
Aider	Quick CLI assistant	Small tasks, one-off fixes, simple edits
Playwright	Browser automation	E2E testing, API call simulation, UI testing
E2B	Sandboxed execution	Running generated code safely

Installation

Prerequisites

• Node.js 18+ (for Playwright, OpenCode)
• Python 3.10+ (for Aider)
• Git (for repository management)
• Access to npm and pip

1. Install OpenCode (Recommended for Self-Hosted)

# Download from GitHub (OpenCode is open-source, self-hosted)
# Visit: https://github.com/anomalyco/opencode/releases
# Run the installer for your platform

# OR use npm package (if available in registry)
npm install -g opencode

# Verify installation
opencode --version

Important: OpenCode is the open-source tool. Do not confuse with Claude Code (Anthropic's service).

Configuration:

• OpenCode reads AGENTS.md for project context
• Create/Edit: n:\Data\Users\David\MyWorkspace\@projectname\AGENTS.md
• Task briefs go in: <project-root>/task-brief.md

2. Install Aider

# Install via pip
pip install aider-chat

# Verify installation
aider --version

# Basic usage
aider project-folder --model ollama/<your-model>

Aider Configuration:

• Create/Edit: .aider.conf.yml in project root
• Example:

model: ollama/llama3.2
max_messages: 50
user_instructions: "Read AGENTS.md for project context"

3. Install Playwright

# Install as npm dev dependency (for browser automation in projects)
npm install -D @playwright/test

# Install browsers
npx playwright install

# Verify installation
npx playwright --version

# Example usage in project:
# playwright.config.ts
# Tests run via: npx playwright test

4. Install E2B (Optional)

# For sandboxed code execution
npm install @e2b/sdk

# Example usage in project:
# const { Sandbox } = require('@e2b/sdk');
# const sandbox = await Sandbox.create({...});

Usage Patterns

Quick Reference

Task	Tool	Command
Simple file edit	Aider	aider
Test harness debugging	OpenCode	opencode --task task-brief.md
Browser E2E testing	Playwright	npx playwright test
Code snippet validation	E2B	See sandbox examples

OpenCode Workflow

1. Prepare project context:

   • Ensure AGENTS.md exists in project root
   • Document build/test commands, architecture, conventions

2. Create task brief:

   # task-brief.md
   
   ## Context
   Need to add Playwright tests for API endpoints
   
   ## Goal
   Implement E2E tests for user authentication flow
   
   ## Acceptance Criteria
   - [ ] Tests pass for happy path
   - [ ] Tests fail appropriately for invalid auth
   - [ ] Tests run under 5 minutes
   
   ## Constraints
   - Don't modify authentication service code
   - Use existing API patterns
   

3. Launch OpenCode:

   opencode --task task-brief.md
   

4. Review and integrate:

   • OpenCode writes to project files
   • Review changes in IDE
   • Approve/reject as needed

Aider Quick Tasks

# Simple one-off task
aider

# With specific model
aider --model ollama/llama3.2

# With instructions
aider -m "Refactor auth module to use new pattern"

Playwright Project Setup

For browser extension projects:

# Initialize Playwright config
npx playwright init

# Add a new test file
npx playwright test tests/example.spec.ts

# Run with specific browsers
npx playwright test --project=chromium
npx playwright test --project=firefox

Playwright Configuration Example

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
  ],
});

Cross-Project Workflows

Standard Setup Template

When starting a new project:

# 1. Initialize git
git init

# 2. Create AGENTS.md
#    - Project overview
#    - Build/test commands
#    - Architecture notes
#    - Conventions

# 3. Create task-brief.md (for current task)
#    - Context
#    - Goal
#    - Acceptance criteria
#    - Constraints

# 4. Install project dependencies
npm install

# 5. Install Playwright for browser projects
npm install -D @playwright/test

# 6. Configure .clinerules (if project-specific)

Project Memory Files

File	Purpose	Written By	Read By
AGENTS.md	Project context	Cline	All agents
task-brief.md	Current task spec	Cline	OpenCode/Aider
.clinerules	Project-specific guidance	Cline	Cline only
TODOs.txt	Task tracking	Any	All

Evaluation Framework

Tool Selection Matrix

Criteria	OpenCode	Aider	Playwright	E2B
Complex iteration	✓ Best	Limited	N/A	N/A
Simple edits	Good	✓ Best	N/A	N/A
Browser testing	Via Playwright	Via Playwright	✓ Best	N/A
Local models	✓ Supported	✓ Supported	N/A	N/A
Self-hosted	✓ Supported	✓ Supported	N/A	N/A

Cost-Efficiency Considerations

Since you run self-hosted models:

1. Small tasks → Aider (fastest, lowest cost)
2. Iterative debugging → OpenCode (can converge without your input)
3. Browser automation → Playwright (via OpenCode or Aider orchestration)
4. Safe code execution → E2B (when needed)

Monitoring Agent Progress

For OpenCode/Aider sessions:

1. Check logs: Review terminal output for progress indicators
2. Review commits: Git commits show file changes
3. Review TODOs: Check tasks.md for completed items
4. Review chatlog: See @projectname/chatlog.md for session notes

Re-think Triggers:

• 50% time elapsed: Check if task is on track
• 90% time elapsed: Task should be near completion
• 2x time estimate: Re-evaluate approach
• 3x time estimate: Strong re-think needed

Troubleshooting

OpenCode Issues

• Agent not responding: Check model is running (ollama list)
• AGENTS.md not read: Verify file exists in project root
• Permissions denied: Ensure write permissions in project folder

Aider Issues

• Model not found: ollama pull <model-name>
• Large context errors: Increase max_context_tokens in config

Playwright Issues

• Browser download fails: Run npx playwright install --with-deps
• Network errors: Check proxy settings in config

Next Steps

1. Install tools (toggle to Act mode when ready)
2. Create AGENTS.md for existing projects
3. Test workflow with LinkdingSync test harness
4. Document lessons in docs/ folder

Additional Resources

• OpenCode Documentation
• Cline Customization
• Aider Documentation
• Playwright Documentation
• E2B Documentation