Jonno

G'day! Jonno here - your tireless Aussie dev mate!

Jonno is an autonomous development loop that works with Claude Code CLI, OpenCode CLI and others to iteratively complete tasks defined in a structured specification format.

Prerequisites

Before using Jonno, ensure you have the following installed:

| Requirement | Version | Notes | | ------------------- | --------- | ------------------------------------------------------ | | Node.js | >= 18.0.0 | Required | | bash | Any | Ships with macOS/Linux | | jq | Any | JSON processor - brew install jq or apt install jq | | Claude Code CLI | Latest | npm install -g @anthropic-ai/claude-code | | OpenCode CLI | Latest | Alternative to Claude Code (optional) | | GitHub Copilot CLI | Latest | npm install -g @github/copilot (optional) | | fswatch | Any | Optional - for efficient file watching |

Platform Support: Linux and macOS only. Windows is not currently supported.

Features

• Multi-Feature Projects: Organize your project into multiple independent features, each with its own PRD, tasks, and progress tracking
• Autonomous Task Execution: Reads tasks from feature-specific features.json and executes them one by one
• Multi-Agent Support: Works with Claude Code CLI, OpenCode CLI, and GitHub Copilot CLI
• Interactive Permission Handling: Prompts for approval on sensitive operations
• Progress Tracking: Maintains a log of completed iterations per feature
• Model Escalation: Automatically uses stronger models for architectural phases or after failures
• Project-Local State Storage: Logs and state stored in .logs/jonno/ for portability
• Configurable Verification: Optionally run a verification script after each iteration

Installation

npm install -g jonno

Or use with npx:

npx jonno init

Quick Start

1. Initialize a new project:

   cd your-project
   npx jonno init

   This creates a main feature by default with the following structure:

   your-project/
   ├── .jonnorc                          # Configuration
   ├── AGENTS.md                         # Agent guidelines (shared)
   └── specs/
       ├── TECH_STACK.md                 # Tech stack (shared)
       └── features/
           └── main/                     # Default feature
               ├── PRD.md                # Product requirements
               ├── features.json         # Task definitions
               └── PROGRESS.md           # Progress log

2. Configure your feature (choose one approach):

   Option A: Interactive builder (recommended)

   npx jonno define main --mode update

   The AI will ask you questions and update the spec files automatically.

   Option B: Manual editing

   • Edit .jonnorc to set your preferences
   • Edit specs/features/main/PRD.md with your product requirements
   • Edit specs/features/main/features.json with your task breakdown
   • Edit AGENTS.md with project-specific guidelines

3. Run the loop:

   npx jonno loop

   If you have only one feature, it runs automatically. With multiple features, you'll see an interactive menu to select one:

   Multiple features found. Select one:
   
     1) auth                 3 pending
     2) dashboard            COMPLETE
     3) main                 5 pending
   
   Enter number [1-3]:

   Or specify directly on the command line:

   npx jonno loop main

4. Monitor progress (in a separate terminal):

   npx jonno watch

CLI Commands

| Command | Description | | --------------------------------- | ---------------------------------------------- | | jonno init [--force] | Initialize Jonno in current project | | jonno define [feature] [--mode] | Interactive feature builder (create or update) | | jonno loop [feature] [iters] | Run the development loop for a feature | | jonno feature new <name> | Create a new feature (from template) | | jonno feature list | List all features with status | | jonno feature remove <name> | Remove a feature (requires --force) | | jonno lima [subcommand] | Lima VM management (macOS only) | | jonno watch | Start file watcher in separate terminal | | jonno logs [file] | Format JSON log files for readability | | jonno status [feature] | Show current loop status | | jonno clean [--force] | Remove state directory for this project | | jonno help | Show help message |

Interactive Feature Builder

The define command launches an interactive session where the AI agent asks you questions about your feature and automatically generates all the spec files.

When run without arguments, it shows an interactive menu to select an existing feature or create a new one:

npx jonno define

# Output:
#   Select a feature to work with:
#
#     n) Create a new feature
#
#   Or update an existing feature:
#
#     1) auth                 3/5 done
#     2) dashboard            COMPLETE
#
#   Enter choice [n, 1-2]:

You can also specify a feature directly:

# Create a new feature with a specific name
npx jonno define my-feature

# Update an existing feature
npx jonno define auth --mode update

The agent will ask about:

• Feature name and problem statement
• Primary goals and target users
• Core capabilities and success criteria
• Technical constraints and out-of-scope items

Then it generates PRD.md, features.json, jonnorc.json, and PROGRESS.md for you.

Working with Features

# Create a new feature from template (manual editing required)
npx jonno feature new auth

# Or use the interactive builder (recommended)
npx jonno define auth

# List all features and their progress
npx jonno feature list

# Run loop for a specific feature
npx jonno loop auth

# Run 50 iterations for a feature
npx jonno loop auth 50

# Remove a feature (with confirmation)
npx jonno feature remove auth --force

Configuration

Create a .jonnorc file in your project root (generated by jonno init):

{
  "agent": "claude",
  "specs": {
    "agents": "AGENTS.md",
    "techStack": "specs/TECH_STACK.md",
    "featuresDir": "specs/features"
  },
  "models": {
    "claude": {
      "default": "claude-sonnet-4-5-20250929",
      "strong": "claude-opus-4-5-20251101"
    },
    "opencode": {
      "default": "anthropic/claude-sonnet-4-5-20250929",
      "strong": "anthropic/claude-opus-4-5-20251101"
    },
    "copilot": {
      "default": "claude-sonnet-4.5",
      "strong": "claude-opus-4.5",
      "coAuthor": null
    }
  },
  "maxIterations": 100,
  "verify": {
    "enabled": false,
    "script": "scripts/verify.sh",
    "runOn": "failure"
  }
}

Configuration Options

| Option | Description | | ------------------- | ------------------------------------------------------ | | agent | CLI to use: "claude", "opencode", or "copilot" | | specs.agents | Path to agent guidelines file (shared across features) | | specs.techStack | Path to tech stack file (shared across features) | | specs.featuresDir | Directory containing feature subdirectories | | models.claude.* | Model names for Claude Code CLI | | models.opencode.* | Model names for OpenCode CLI (provider/model format) | | models.copilot.* | Model names for GitHub Copilot CLI | | maxIterations | Maximum iterations before stopping | | verify.enabled | Whether to run verification script | | verify.script | Path to verification script | | verify.runOn | When to run: "always", "failure", or "never" |

Environment Variables

| Variable | Description | | ----------------- | ------------------------------------------------- | | AGENT_CLI | Override CLI selection (claude, opencode, or copilot) | | JONNO_STATE_DIR | Override state directory (default: .logs/jonno) | | JONNO_DEBUG | Set to 1 for debug output | | VERBOSE | Set to 1 for verbose agent output (Claude only) | | STREAM | Set to 1 for JSON streaming output | | FORMAT | Set to 1 for formatted real-time output |

Project Structure

Jonno organizes your project with multi-feature support. Each feature is self-contained with its own requirements, tasks, and progress tracking.

your-project/
├── .jonnorc                          # Configuration
├── AGENTS.md                         # Agent guidelines (shared)
└── specs/
    ├── TECH_STACK.md                 # Tech stack (shared)
    └── features/
        ├── main/                     # Default feature
        │   ├── PRD.md
        │   ├── features.json
        │   └── PROGRESS.md
        ├── auth/                     # Another feature
        │   ├── PRD.md
        │   ├── features.json
        │   └── PROGRESS.md
        └── dashboard/                # Yet another feature
            ├── PRD.md
            ├── features.json
            └── PROGRESS.md

Shared Files

• AGENTS.md - Guidelines and conventions for the AI agent (shared across all features)
• specs/TECH_STACK.md - Technical stack and constraints (shared across all features)

Per-Feature Files

Each feature directory contains:

• PRD.md - Product requirements document for this feature
• features.json - Task definitions for this feature
• PROGRESS.md - Auto-generated log of completed iterations
• jonnorc.json - Feature-specific configuration (optional)

Per-Feature Configuration

Each feature can have its own jonnorc.json file with feature-specific settings:

{
  "strongModelPhases": ["phase-0", "phase-1", "phase-2", "phase-5"],
  "maxIterations": 100
}

| Option | Description | | ------------------- | ---------------------------------------------------------- | | strongModelPhases | Phases that should use the stronger model for this feature | | maxIterations | Maximum iterations for this feature |

The strongModelPhases setting controls which phases use the stronger model (e.g., Opus) instead of the default model (e.g., Sonnet). This is useful for complex architectural phases that benefit from more capable reasoning.

Default phases using the stronger model: ["phase-0", "phase-1", "phase-2", "phase-5"]

features.json Format

Defines the tasks to be completed:

{
  "phases": [
    {
      "id": "phase-0",
      "name": "Project Setup",
      "sections": [
        {
          "id": "section-0-1",
          "name": "Environment",
          "tasks": [
            {
              "id": "task-0-1-1",
              "description": "Initialize project structure",
              "passes": false
            }
          ]
        }
      ]
    }
  ]
}

State Directory

Jonno stores logs and state in a project-local .logs/jonno/ directory, organized by feature. This makes projects fully portable and Lima/VM-friendly.

your-project/
├── .logs/                        # Auto-added to .gitignore
│   └── jonno/
│       ├── logs/
│       │   ├── main/             # Logs for 'main' feature
│       │   │   ├── combined.log
│       │   │   └── iteration_001.log
│       │   └── auth/             # Logs for 'auth' feature
│       │       ├── combined.log
│       │       └── iteration_001.log
│       └── state/
│           ├── main/             # State for 'main' feature
│           │   ├── status.txt
│           │   └── last_features_hash
│           ├── auth/             # State for 'auth' feature
│           │   ├── status.txt
│           │   └── last_features_hash
│           └── jonno.pid         # Process PID file
└── ...

The jonno init command automatically adds .logs to your .gitignore file.

Verification Script

If you want to run verification after each iteration:

1. Create scripts/verify.sh:

   #!/bin/bash
   npm run lint && npm run typecheck && npm run build

2. Configure in .jonnorc:

   {
     "verify": {
       "enabled": true,
       "script": "scripts/verify.sh",
       "runOn": "always"
     }
   }

Options for runOn:

• "always" - Run at the start of each iteration
• "failure" - Run only after a failed iteration
• "never" - Never run (same as enabled: false)

Lima VM Isolation (macOS)

When running autonomous AI agents, there's an inherent risk: the agent executes arbitrary code and shell commands on your machine. A malicious prompt injection, compromised dependency, or unexpected agent behavior could potentially:

• Delete or modify files outside your project
• Access sensitive credentials or environment variables
• Install unwanted software or malware
• Exfiltrate data from your system

Lima VM isolation mitigates these risks by running the agent inside a lightweight Linux virtual machine. The agent can only access your project directory (mounted read-write), while the rest of your system remains protected.

Lima Commands

| Command | Description | | --------------------- | ---------------------------------------- | | jonno lima | Interactive menu to select an option | | jonno lima setup | Full VM setup with agent authentication | | jonno lima auth | Re-authenticate agent CLI in existing VM | | jonno lima shell | Open interactive shell inside the VM | | jonno lima teardown | Remove the VM completely |

Quick Start with Lima

# Set up Lima VM (installs Lima via Homebrew if needed)
npx jonno lima setup

# Run your development loop (automatically uses VM)
npx jonno loop

# When done, remove the VM
npx jonno lima teardown

How It Works

1. VM Creation: Creates a Lima VM using the default Ubuntu template
2. Project Mount: Mounts your project directory with write access
3. Agent Installation: Installs Node.js and your chosen agent CLI (Claude Code, OpenCode, or GitHub Copilot) inside the VM
4. Authentication: Captures authentication URLs from the VM and opens them on your Mac
5. Transparent Execution: Once configured, jonno loop automatically runs the agent inside the VM

Configuration

After running jonno lima setup, your .jonnorc is updated with "lima": true. This tells Jonno to prefix all agent commands with limactl shell <vm-name> --, transparently executing them inside the VM.

To disable Lima and run agents directly on your host:

{
  "lima": false
}

Requirements

• macOS only (Lima uses Apple's Virtualization framework)
• Homebrew (for installing Lima if not present)
• Sufficient disk space for the VM (~5GB)

Tips

• Start small: Begin with a few well-defined tasks to test your setup
• One feature at a time: Focus on completing one feature before starting another
• Use feature list: Run jonno feature list to see progress across all features
• Watch the logs: Use jonno watch in a separate terminal to see real-time progress
• Use verification: Enable verification to catch issues early
• Iterate on specs: If tasks are failing, refine your PRD and task descriptions
• Check context: If context length is exceeded, Jonno will trim PROGRESS.md automatically

License

MIT

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

No worries, I've got this! 🦘