Initial commit: LinkSyncServer and LinkSyncExtension projects with complete documentation, models, API endpoints, tests, and extension implementation
This commit is contained in:
DavidSaylor
304
docs/agent-tools-installation.md
Normal file
304
docs/agent-tools-installation.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```yaml
|
||||
model: ollama/llama3.2
|
||||
max_messages: 50
|
||||
user_instructions: "Read AGENTS.md for project context"
|
||||
```
|
||||
|
||||
### 3. Install Playwright
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```markdown
|
||||
# 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:**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```typescript
|
||||
// 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:
|
||||
|
||||
```bash
|
||||
# 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](https://open-code.ai/en/docs)
|
||||
- [Cline Customization](https://docs.cline.bot/customization/overview)
|
||||
- [Aider Documentation](https://aider.github.io/)
|
||||
- [Playwright Documentation](https://playwright.dev/)
|
||||
- [E2B Documentation](https://e2b.dev/)
|
||||
Reference in New Issue
Block a user