journeyman-cli 1.1.0

Route implementation tasks to a local or economical model

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:

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:

# 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

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:

# 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