# OpenCode Agent Instructions

## Overview

This repository contains an OpenCode development environment setup. OpenCode is an AI-powered development assistant that helps you build, test, and deploy software. The environment is configured with the OpenCode plugin and runs in a Linux-based development container.

## Project Context

- **Project Type**: AI Agent Development Environment
- **Main Technology**: Node.js with OpenCode plugin
- **Target Audience**: AI agents and developers working on code generation projects
- **Development Server**: Local development with Ollama for on-premise LLMs

## Development Environment

### System Setup

- **OS**: Debian Linux (running in Proxmox container)
- **IP Address**: 192.168.0.240
- **Memory**: Standard Linux environment with Node.js
- **AI Models**: Ollama server at http://192.168.0.50:11434 (gemma2:9b, nomic-embed-text)

### Key Directories

- `.opencode/` - OpenCode plugin and configuration
- `.opencode/memory/` - Persistent memory storage
- `.opencode/node_modules/` - Node.js dependencies

## OpenCode Usage

### Basic Commands

```bash
# Start OpenCode agent
opencode

# Run with specific tool
opencode --tool claude

# Check OpenCode version
opencode --version
```

### Agent Workflow

1. **Initialization**: OpenCode loads the project context and available skills
2. **Task Analysis**: The agent analyzes the request and breaks it down into steps
3. **Execution**: Tasks are delegated to specialized subagents
4. **Verification**: Results are checked against requirements
5. **Documentation**: Progress is saved to memory and AGENTS.md

## Important Development Commands

### Node.js Management

```bash
# Install dependencies
npm install

# Run scripts (if defined in package.json)
npm run <script-name>

# Check for outdated packages
npm outdated

# Update packages
npm update
```

### Git Operations

```bash
# Check status
git status

# Add changes
git add .

# Commit changes
git commit -m "message"

# Push to remote
git push
```

### File Operations

```bash
# Search for files
find . -name "*.js" -type f

# Search content
grep -r "pattern" .

# List all files
ls -la
```

## Testing and Debugging

### Diagnostic Tools

- **lsp_diagnostics**: Check for errors and warnings in files
- **grep**: Search for patterns across the codebase
- **ast_grep**: Advanced code pattern matching
- **read**: Read file contents

### Debugging Strategy

1. Use `lsp_diagnostics` to identify issues
2. Search for similar patterns with `grep` or `ast_grep`
3. Consult documentation for external libraries
4. Test changes in isolation
5. Verify with build/test commands

## Conventions and Best Practices

### Code Quality

- **Type Safety**: Never suppress type errors with `as any` or `@ts-ignore`
- **Error Handling**: Always handle errors properly; avoid empty catch blocks
- **Testing**: Write tests for new functionality; don't delete failing tests
- **Refactoring**: Refactor safely; use tools to ensure correctness

### Workflow

- **Atomic Commits**: Each commit should represent a single logical change
- **PRs**: Keep pull requests focused and small
- **Documentation**: Update documentation as part of any significant change
- **Memory**: Use memory files to persist important information

## Common Gotchas

### Environment Issues

- **Node.js Version**: Ensure you're using a compatible Node.js version
- **Dependencies**: Install all dependencies before running commands
- **Permissions**: Check file permissions for read/write access

### OpenCode Specific

- **Context Window**: Keep requests focused to avoid context overflow
- **Skill Selection**: Use appropriate skills for the task domain
- **Background Tasks**: Use `run_in_background=true` for parallel operations
- **Task Continuation**: Use `task_id` to continue previous agent sessions

## External Resources

### Documentation Links

- [OpenCode Documentation](https://opencode.ai/docs)
- [Node.js Documentation](https://nodejs.org/docs)
- [Ollama Documentation](https://ollama.com/docs)

### Local Servers

- **Ollama**: http://192.168.0.50:11434
- **Development Server**: (if applicable)

## Project-Specific Notes

This is a minimal development environment primarily used for:
- Testing OpenCode agent capabilities
- Developing AI-assisted coding workflows
- Experimenting with on-premise LLM integration

The repository is intentionally simple to serve as a clean slate for various development tasks.

## Updating This File

Keep AGENTS.md up to date with any new conventions, commands, or structural changes. Remove outdated information and add new insights as they're discovered.

(End of file)