Metadata-Version: 2.4
Name: journeyman-cli
Version: 1.1.0
Summary: Route implementation tasks to a local or economical model
Author: Rajat Garg
License: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Description-Content-Type: text/markdown

# journeyman

**Save your frontier tokens for thinking. A local or economical model writes every line of code — and tight specs make small models write it well.**

`journeyman` is an Agent Skill designed to plug into **Claude Code**, **Codex CLI**, **Cursor**, **GitHub Copilot**, and **Gemini CLI**. It is built on a simple division of labor:
1. **The Frontier Agent (Claude/GPT/Gemini)** acts as the architect. It writes plans, tests, and highly specific per-file specs. It *never* writes the application source code directly.
2. **The Worker Model (Local or Low-Cost Remote)** types out the actual code based on those tight specs.

By enforcing this contract, you save expensive API tokens on repetitive code generation, and you force small models to generate high-quality code because they are never given vague prompts.

---

## Quick Start

### 1. Install the CLI

You can install `journeyman` directly as a Python package from the repository root:

```bash
git clone <this-repo-url> journeyman
cd journeyman
pip install .
```

Alternatively, you can run `./install.sh` which runs `pip install` and registers the skill for Claude Code under `~/.claude/skills/journeyman`. (Use `./install.sh --copy` for a standalone copy-mode installation.)

### 2. Configure your Worker Model

`journeyman` is zero-config if you run a local model server. It automatically detects and connects to **Ollama** (port 11434), **LM Studio** (1234), **llama.cpp**, and **mlx_lm** (8080).

If you don't have local hardware, you can fall back to fast, low-cost remote providers:

```bash
# See all available backends (local and remote)
journeyman setup --list

# Set a preferred remote fallback (requires GROQ_API_KEY in your environment)
journeyman setup --prefer-remote groq

# Or store a key in the config file (mode 0600; env vars still win)
journeyman setup --set-api-key groq "$GROQ_API_KEY"
```

### 3. Integrate with your Agent

Journeyman ships with ready-to-paste integration templates. Just copy the contents of the relevant file into your project:

| Agent | File to edit | Template to copy |
|---|---|---|
| **Claude Code** | `CLAUDE.md` in project root | `templates/CLAUDE.md` |
| **Codex CLI** | `AGENTS.md` in project root | `templates/AGENTS.md` |
| **Cursor** (current) | `.cursor/rules/journeyman.mdc` | `templates/journeyman.mdc` |
| **Cursor** (legacy) | `.cursorrules` in project root | `templates/cursorrules` |
| **GitHub Copilot** | `.github/copilot-instructions.md` | `templates/copilot-instructions.md` |
| **Gemini CLI** | `GEMINI.md` in project root | `templates/GEMINI.md` |

Once added, just tell your agent: *"Use journeyman to build a CLI todo app."*

---

## How it Works

```text
you ──"build X"──▶ frontier agent (Claude / Gemini / GPT)
                     │  1. writes architecture and per-file specs
                     │  2. invokes journeyman ──▶ local or economical model
                     │                         (writes the file)
                     │  3. reviews the code, runs tests
                     │  4. on failure: improves the SPEC and re-delegates
                     ▼
                 working, reviewed code — written locally or via a low-cost remote
```

The worker script (`journeyman worker`) validates the generated code (Python: `py_compile`; JS: `node --check`; TS: `tsc --noEmit`; Bash: `bash -n`) and handles automatic retries if the local model messes up, before passing control back to the frontier agent for final review.

---

## Manual CLI Usage

You can use `journeyman` manually without an agent. The worker takes a markdown spec and outputs a validated file:

```bash
# Pipe a spec directly (preferred for agents)
journeyman worker --task - --out src/parser.py --expect 'class Parser' <<'SPEC'
# Task: Create a CSV parser
## Output file
src/parser.py
## Language & Runtime
Python 3.11+
## Signatures
class Parser: ...
SPEC

# Or use a spec file
journeyman worker --task tasks/01-parser.md --out src/parser.py --stream
```

### CLI Options

| Flag | Description |
|---|---|
| `--task FILE` | Spec file (Markdown), or `-` for stdin |
| `--out FILE` | Output file path |
| `--context FILE...` | Read-only context files to inject |
| `--expect PATTERN` | Regex that must appear in output |
| `--json-output` | Write JSON result summary to stdout (for agent consumption) |
| `--stream` | Show output as it is generated (to stderr) |
| `--lang` | Override auto-detected language (`python`, `javascript`, `typescript`, `bash`) |
| `--no-validate` | Skip syntax check |
| `--no-backup` | Overwrite without creating a `.bak` copy |
| `--timeout SECONDS` | HTTP timeout for model API calls (default: 120) |
| `--root DIR` | Project root; relative paths resolve from here |

---

## Requirements & Trust

- **Python 3.7+** (No external dependencies; standard library only).
- **Data flow**: If you use a local backend (Ollama/LM Studio), **no data leaves your machine**. If you use a remote fallback, specs and injected context files are sent to that API.
- **Safety**: `journeyman` performs atomic writes. If a file exists, it automatically creates a `.bak` copy before overwriting.

## Exit Codes

Agents rely on strict exit codes to manage the workflow:

| Code | Meaning | Agent Action |
|---|---|---|
| **0** | Success — validated output written | Review the output |
| **1** | No code block in response | Tighten spec and retry |
| **2** | Config, argument, or network error | Do NOT retry; ask user to check setup |
| **3** | Validation failed after max retries | Fix the file directly |
| **4** | Stream interrupted | Retry |
| **5** | `--expect` pattern missing after retries | Tighten expect/signatures; retry |

---
*License: MIT*
