Looper-Go Development

Overview

Looper-Go is a Go implementation of the autonomous AI loop runner. This skill covers common development workflows.

Project Structure

looper-go/
├── cmd/looper/          # CLI entry point
├── internal/
│   ├── config/          # Configuration loading
│   ├── agents/          # Agent runners
│   ├── loop/            # Main orchestration
│   ├── todo/            # Task file handling
│   ├── prompts/         # Prompt templates
│   ├── logging/         # JSONL logging
│   └── hooks/           # Post-iteration hooks
├── prompts/             # Bundled prompt templates
└── to-do.json           # Task file (runtime)

Common Commands

Build

bash
1# Build binary
2go build ./cmd/looper
3
4# Build to custom location
5go build -o ~/bin/looper ./cmd/looper
6
7# Build for multiple platforms
8go build -o bin/looper-linux ./cmd/looper
9GOOS=darwin go build -o bin/looper-macos ./cmd/looper
10GOOS=windows go build -o bin/looper.exe ./cmd/looper

Test

bash
1# Run all tests
2go test ./...
3
4# Run with coverage
5go test -cover ./...
6
7# Run specific package
8go test ./internal/loop
9
10# Verbose output
11go test -v ./internal/loop
12
13# Run make test (includes smoke tests)
14make test

Run

bash
1# Default run (uses to-do.json in current dir)
2looper run
3
4# Specify max iterations
5LOOPER_MAX_ITERATIONS=5 looper run
6
7# Run with specific task file
8looper --task-file path/to/tasks.json run
9
10# View logs
11looper tail
12
13# List tasks
14looper ls
15
16# Show config
17looper config
18
19# Check dependencies
20looper doctor

Debug

bash
1# Enable debug logging
2LOOPER_DEBUG=1 looper run
3
4# View JSONL logs
5looper tail
6
7# View specific run
8looper tail --run <run-id>
9
10# Validate task file
11looper validate
12
13# Format task file
14looper fmt

Development Workflow

1. Make Changes

Edit code in internal/ or cmd/ as needed.

2. Test Changes

bash
1# Run unit tests
2go test ./...
3
4# Run smoke tests
5make test
6
7# Run live test
8~/.codex/skills/looper-live-test/scripts/run-live-test.sh

3. Commit Changes

bash
1# Check status
2git status
3
4# Run pre-commit hooks (if installed)
5pre-commit run --all-files
6
7# Commit
8git commit -m "feat: description"

4. Build and Install

bash
1# Build
2go build ./cmd/looper
3
4# Install to PATH
5go install ./cmd/looper

Configuration

Config File Locations (priority order)

1. .looper/config.json - Project-specific
2. ~/.config/looper/config.json - User config
3. Environment variables (LOOPER_*)
4. CLI flags

Example Config

json
1{
2  "max_iterations": 100,
3  "agent": {
4    "type": "claude",
5    "model": "claude-3-5-sonnet-20241022"
6  },
7  "paths": {
8    "log_dir": "./looper-logs"
9  }
10}

Key Environment Variables

Troubleshooting

Build Fails

bash
1# Clean and rebuild
2go clean -cache
3go mod tidy
4go build ./cmd/looper

Tests Fail

bash
1# Run verbose to see details
2go test -v ./...
3
4# Check specific package
5go test -v ./internal/loop

Agent Not Found

bash
1# Check config
2looper config
3
4# Verify agent binary exists
5which codex
6which claude
7
8# Check in config
9cat .looper/config.json | jq '.agent'

Adding New Features

1. Add Internal Package

bash
1mkdir internal/feature
2# Create feature.go

2. Add Tests

bash
1# Create feature_test.go
2go test ./internal/feature

3. Wire Into Loop

Edit internal/loop/loop.go to use new feature.

4. Update Documentation

• Edit ARCHITECTURE.md if structural change
• Edit README.md if user-facing
• Add godoc comments

Release Process

Use the release-runbook skill:

bash
1~/.codex/skills/release-runbook/scripts/release.sh --version 1.2.3 --test-cmd "make test"

Code Style

• Standard Go formatting (gofmt)
• Conventional commits for commit messages
• Add tests for new functionality
• Update documentation

Resources

• ARCHITECTURE.md - Full architecture documentation
• README.md - User documentation
• CONTRIBUTING.md - Contribution guidelines
• AI_POLICY.md - AI contribution policy