Coly — AI coding CLI powered by Puter

Coly is an AI coding assistant powered by Puter. It uses Claude Opus 4.8 (or any Puter-accessible model) for planning and reasoning, with intelligent model routing to lighter models for routine tasks.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    User Task                                │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│  Fable 5 Orchestrator  (FLAGSHIP tier — Claude Fable 5)     │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Phase 1: Plan                                       │  │
│  │  - Decompose task into structured steps               │  │
│  │  - Assign complexity tier per step                    │  │
│  │  - Identify verification requirements                 │  │
│  └───────────────────┬───────────────────────────────────┘  │
│                      │                                       │
│  ┌───────────────────▼───────────────────────────────────┐  │
│  │  Phase 2: Execute Steps (Model Router)                │  │
│  │                                                       │  │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐            │  │
│  │  │ FLAGSHIP │  │ STANDARD │  │   FAST   │            │  │
│  │  │ (Complex │  │ (Routine │  │ (Trivial │            │  │
│  │  │  Reasoning│) │   Code)  │) │   Tasks) │            │  │
│  │  └──────────┘  └──────────┘  └──────────┘            │  │
│  └───────────────────┬───────────────────────────────────┘  │
│                      │                                       │
│  ┌───────────────────▼───────────────────────────────────┐  │
│  │  Phase 3: Synthesize (FLAGSHIP)                       │  │
│  │  - Combine step results into coherent final output    │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│  Verification System                                       │
│  - Sanity checks │ TypeScript compilation │ File refs      │
└─────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│  Human-in-the-Loop Gate                                    │
│  - Low risk: auto-approve                                  │
│  - Medium risk: log warning                                │
│  - High/Critical risk: require human approval              │
└─────────────────────────────────────────────────────────────┘

Key Features

| Feature | Description | |---------|-------------| | Fable 5 Orchestrator | Uses Claude Fable 5 for planning, decomposition, and synthesis | | Intelligent Model Routing | Routes tasks to the right model based on complexity, risk, and keywords | | Puter.js SDK | Access frontier models via Puter — no API keys needed | | Self-Verification | Automatically runs checks before accepting results | | Human-in-the-Loop | Configurable approval gates for high-risk actions | | Extensible Tool System | Built-in file, bash, and search tools | | Worker Agents | Lightweight agents for routine execution |

Getting Started

1. Install

npm install fable5puter

2. Configuration

Puter does not use API keys. Copy the example env file:

cp .env.example .env

Configure your model preferences:

FABLE5_MODEL=claude-opus-4-8
LIGHT_MODEL=claude-sonnet-4-20250514
FAST_MODEL=gpt-4o-mini

Auth options — Puter does not use API keys:

| Method | Config | |--------|--------| | Inside Puter hosting | No config needed — auth is automatic | | Auth token in .env | PUTER_AUTH_TOKEN=your-token | | Interactive (browser) | Default — opens browser for login |

3. Basic Usage

import { Orchestrator } from 'fable5puter';

const orchestrator = new Orchestrator();

const result = await orchestrator.run({
  description: 'Analyze the project structure and suggest improvements',
  riskLevel: 'low',
  requiresPlanning: true,
  context: { projectType: 'TypeScript' },
});

console.log(result.output);

Model Routing Strategy

| Tier | Example Models | When to Use | |------|---------------|-------------| | FLAGSHIP | claude-opus-4-8 (or claude-fable-5 if available) | High-risk tasks, architectural planning, complex debugging | | STANDARD | claude-sonnet-4-20250514 | Code generation, refactoring, test writing | | FAST | gpt-4o-mini | Formatting, summarization, simple lookups |

Routing Rules

• Risk-based: HIGH/CRITICAL risk → FLAGSHIP
• Planning-based: Tasks requiring decomposition → FLAGSHIP
• Keyword-based: Descriptions matching architect, plan, strategy → FLAGSHIP; format, convert, summarize → FAST
• Fallback: Everything else → STANDARD

Components

Orchestrator

Central planner. Takes a high-level task, decomposes it into steps using Fable 5, executes each step via the appropriate model tier, and synthesizes results.

Model Router

Decides which model handles which task/step based on complexity, risk, and content analysis.

Worker Agent

Lightweight agent for executing individual steps. Uses STANDARD or FAST tier by default.

Tool System

Extensible framework. Built-in tools: read_file, bash, search.

Verification System

Automatic checks: output sanity, file reference validation, TypeScript compilation, step failure detection.

Human-in-the-Loop Gate

Approval workflow:

• Low risk: Auto-approved
• Medium risk: Auto-approved with warning
• High/Critical risk: Interactive prompt or programmatic API

Testing

npm test          # Run test suite (26 tests)
npm run build     # TypeScript compilation
npm run lint      # Lint check

How Puter Auth Works

Puter.js SDK handles authentication transparently:

1. Inside Puter hosting: The SDK detects the environment and works automatically — no tokens or keys needed
2. External with token: Set PUTER_AUTH_TOKEN in your .env
3. Interactive: If no token is set and not inside Puter, the SDK opens a browser window for you to authenticate

The SDK communicates with https://api.puter.com using an internal driver protocol, not a REST API. This means you don't need to manage individual API keys for each AI provider.

License

MIT