Skip to content

usage.md

Latest commit

 

History

History
382 lines (275 loc) · 7.59 KB

usage.md

File metadata and controls

382 lines (275 loc) · 7.59 KB
Raw

opencoder - Usage Guide

This guide covers how to effectively use opencoder in different environments and workflows.

Basic Usage

Host Environment

After running ./scripts/local-setup.sh, OpenCode is available globally with the opencoder configuration installed:

# Basic OpenCode commands
opencode --version
opencode --help
opencode  # Start interactive TUI

# Start OpenCode with opencoder configuration
opencode

The opencoder configuration includes these OpenCode plugins:

  • @tarquinen/opencode-dcp@3.1.13
  • cc-safety-net@1.0.6
  • oh-my-openagent@4.12.0

Container Environment

The container comes with OpenCode pre-configured and ready to use:

# Check installation
podman run -it --rm opencoder opencode --version

# Interactive session
podman run -it --rm opencoder

# Run specific commands
podman run --rm opencoder opencode --help

Development Workflows

Project Development

Mount your project directory to work on existing codebases:

# Mount current directory as workspace
podman run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  opencoder bash

# Direct command execution
podman run --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  opencoder opencode --version

Multi-Agent Orchestration

The opencoder includes oh-my-openagent for sophisticated multi-agent workflows:

# Start orchestration session
opencode

# Available agents (examples):
# - Sisyphus: Main orchestrator
# - Hephaestus: Deep autonomous worker
# - Prometheus: Strategic planner
# - Oracle: Architecture consultant
# - Librarian: Documentation and research

Skills and Commands

Access production-ready skills and commands:

# Skills are loaded automatically from plugins

# Use specific skills in your workflow
# - TDD workflows
# - Git operations
# - Browser automation (Playwright)
# - Debugging methodologies

Container Usage Patterns

Development Environment

Interactive development:

# Start development container
podman run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  --name opencode-dev \
  opencoder bash

# Inside container
opencode --version
ls -la /workspace

Persistent containers:

# Create persistent container for long-running work
podman run -dit \
  -v $(pwd):/workspace \
  -w /workspace \
  --name my-opencode-env \
  opencoder

# Attach to existing container
podman exec -it my-opencode-env bash

# Stop when done
podman stop my-opencode-env
podman rm my-opencode-env

CI/CD Integration

GitHub Actions example:

name: OpenCode Check
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check OpenCode version
        run: |
          podman pull ghcr.io/tankdonut/opencoder:latest
          podman run --rm \
            -v ${{ github.workspace }}:/workspace \
            -w /workspace \
            ghcr.io/tankdonut/opencoder:latest \
            opencode --version

GitLab CI example:

check-opencode:
  stage: test
  image: ghcr.io/tankdonut/opencoder:latest
  script:
    - opencode --version
  only:
    - merge_requests
    - main

Team Collaboration

Consistent environments:

# Team members use same container version
podman pull ghcr.io/tankdonut/opencoder:v1.0.0

# Shared configuration via mounted configs
podman run -it --rm \
  -v $(pwd):/workspace \
  -v ~/team-opencode-config:/config \
  -w /workspace \
  opencoder

Workspace mount:

# Mount a project workspace with the opencoder configuration
podman run -it --rm \
  -v $(pwd):/workspace \
  -w /workspace \
  opencoder

Plugin Management

Updating Plugins

The opencoder uses the skills.sh CLI for skill distribution. Plugins (npm packages) are pinned in opencode.json:

# Update plugin versions in opencode.json, then rebuild
./scripts/build.sh

# Refresh the skills lockfile (baseline skills)
npx skills@1.5.13 experimental_install
git add build/skills-lock.json
git commit -m "update: refresh skills lockfile"

# Container rebuild needed after plugin updates
./scripts/build.sh

Plugin Configuration

Main configuration file: build/.opencode/opencode.json

{
    "$schema": "https://opencode.ai/config.json",
    "plugin": [
        "@tarquinen/opencode-dcp@3.1.13",
        "cc-safety-net@1.0.6",
        "oh-my-openagent@4.12.0"
    ]
}

Container-specific configuration: build/etc/opencode/opencode.jsonc

  • Used for container-specific optimizations
  • Supports comments and trailing commas

Adding Custom Plugins

# Add the plugin to opencode.json with a pinned version
jq '.plugin += ["my-plugin@1.0.0"]' build/.opencode/opencode.json > tmp.json && mv tmp.json build/.opencode/opencode.json

# Add a new skill source at runtime (opt-in)
npx skills@1.5.13 add owner/repo --agent opencode --skill '*' --copy -y

# Rebuild container if using container deployment
./scripts/build.sh

Advanced Usage

Custom Skills Development

Custom skills can be developed following the patterns in the upstream skill repositories linked in the README.

Environment Variables

Environment variables for OpenCode are configured by the tool itself. Refer to the OpenCode documentation for available options.

Debugging and Logging

Access container logs:

# View container logs
podman logs my-opencode-container

# Follow logs in real-time
podman logs -f my-opencode-container

Performance Optimization

Container Performance

Resource limits:

# Limit container resources
podman run -it --rm \
  --memory=4g \
  --cpus=2 \
  -v $(pwd):/workspace \
  opencoder

Volume optimization:

# Use bind mounts for better performance
podman run -it --rm \
  --mount type=bind,source=$(pwd),target=/workspace \
  -w /workspace \
  opencoder

Caching Strategies

Container layer caching:

# Build with tag
./scripts/build.sh --tag opencoder

Plugin caching:

# Skills are baked into the image at build time (oh-my-openagent baseline)
# Optional runtime skills (ECC, superpowers) are fetched on demand
# No additional caching needed for most use cases

Best Practices

Security

  1. Container security:

    • Containers run as non-root user (UID 1000)
    • No secrets baked into images
    • Minimal attack surface

  2. Host security:

    • Keep OpenCode and plugins updated
    • Review plugin permissions
    • Use project-specific configurations

Maintenance

  1. Regular updates:

    # Update opencoder
git pull origin main

 # Rebuild container
 ./scripts/build.sh

  2. Cleanup:

    # Clean up old containers
podman system prune -a

# Clean up unused images
podman image prune -a

Troubleshooting

Common issues and solutions:

  1. Plugin loading failures:

    # Verify plugin config is valid
jq . build/.opencode/opencode.json

# Verify skills lockfile
jq . build/skills-lock.json

# Rebuild from scratch
./scripts/build.sh --no-cache

  2. Container permission issues:

    # Fix workspace permissions
chown -R 1000:1000 /path/to/workspace

  3. Memory/resource issues:

    # Monitor container resource usage
podman stats my-container

# Increase limits if needed
podman run --memory=8g --cpus=4 ...

Getting Help

  • Documentation: Check DEVELOPMENT.md for development-specific usage
  • Issues: Report problems on GitHub Issues
  • Community: Join discussions for user support and tips