fable-session

fable-session is a local Python wrapper for the Claude Code CLI that gives each coding session a small, bounded context before it launches, so routine work is less likely to trip an accidental pause — it is not a model, and it is not an Anthropic product.

Unofficial; not affiliated with Anthropic. This is an independent community tool for operating the Claude Code CLI. It is not made, endorsed, or supported by Anthropic.

This tool does not bypass safeguards. It never retries, rewrites, or re-submits flagged content, never switches models to dodge a refusal, and never makes unsafe work permissible. If a session is paused or refused, fable-session reports that truthfully and stops.

Have you seen this?

The screenshot above reads, word for word:

Session paused

Fable 5's safeguards flagged this message. The safeguards are intentionally broad right now and may flag safe and routine coding, cybersecurity, or biology work. These measures let us bring you Mythos-level capabilities sooner, and we're working to refine them. Send feedback with /feedback or learn more

1. Switch to Opus 4.8
2. Edit prompt and retry with Fable 5

If you keep hitting this pause during ordinary work with Fable 5 in Claude Code, the most common avoidable cause is oversized, unbounded context: a huge prompt, long pasted logs, or a stray trigger word deep in a legacy code dump. fable-session exists to reduce those accidental pauses — honestly, by shaping what goes into a session before launch, never by touching a session after it is flagged.

What it does

• bounded context — each session gets a small, structured brief built from a task file and a repo-owned profile, with a hard byte budget, instead of an unbounded pile of ambient context;
• pinned model, no automatic fallback — the model you request either serves the session or the session stops; nothing silently degrades, switches, or retries;
• evidence afterwards — a post-run model audit reads the session's own structured JSONL stream and proves which models actually served it, and a watchdog reports one session's lifecycle without ever acting on the session.

What it does not do

When a session is genuinely paused or refused, fable-session:

• does not continue a paused run;
• does not edit or retry a flagged prompt;
• does not switch models (options 1 and 2 in the screenshot are choices for you, the human — this tool never takes either of them for you);
• does not weaken or bypass safeguards in any way.

A real pause is recorded and the run stops: the pause is surfaced as a structured event, and what happens next is your decision. The scope of this tool is stopping accidental pauses caused by oversized context, and making every run's outcome provable after the fact.

Why try it?

If you already run Claude Code by hand, each fable-session launch adds four small, practical things:

• a smaller, repeatable task context — one task file plus a byte-budgeted repo profile build the brief, so the same inputs give the same small context every time;
• pinned Fable 5 with no automatic fallback — the pinned model either serves the session or the session stops; nothing silently switches or retries;
• one exact-lane watcher — a single watch --follow on the run's own manifest reports lifecycle events and exits by itself at the terminal state;
• a model and usage audit afterwards — proof, from the session's own JSONL evidence, of which models served it and what it cost.

This can reduce avoidable pause triggers; it does not guarantee that a session is never paused — a real pause still stops the run.

Why trust it?

Every claim here is verified, not promised:

• 500+ automated tests run behind protected-main GitHub CI;
• the runtime is Python standard library only, zero dependencies;
• public-readiness gates scan the tracked tree and every reachable Git blob for internal identifiers and credential-shaped content;
• CI installs the wheel offline and dry-runs the installed CLI;
• every GitHub Action is pinned to exact commit SHAs;
• one real smoke on Linux with Claude Code 2.1.208 ran the whole lifecycle: the task reached Claude on stdin, the launch accepted --max-budget-usd 0.5 (a smoke-test fixture only — a registry with no budget key emits no budget flag), the --follow watcher emitted a bounded usage summary and exited by itself, the session returned the exact marker FABLE_BETA1_SMOKE_OK, and the audit reported PURE for actor messages while honestly reporting auxiliary Haiku use. Total measured cost: $0.15400099999999997.

The compact, privacy-safe record of that smoke — including what it does not prove — is docs/VALIDATION.md.

Who should try it — and who should not

A good fit if:

• you run important or long Claude Code sessions on Fable 5 and want each one launched with a small, bounded, repeatable context;
• you are an operator who needs reproducible evidence — manifests, lifecycle events, and exit codes you can script against;
• you drive sessions from an orchestrator such as Hermes and want one watcher and one audit per lane.

Not a fit:

• it is not a Claude replacement — you still bring your own installed, authenticated Claude Code CLI;
• it never helps bypass safeguards, and it never runs automatic retries or swarms of sessions;
• for a casual one-off chat, registering a project and writing a task file is more ceremony than the chat is worth.

Current limits

The honest edges of this public beta:

• Linux with Claude Code 2.1.208 is the only verified combination; other platforms and CLI versions are unverified;
• Python 3.12+ and tmux are required, and setup is manual — you write the registry, profile, and task files yourself;
• task and brief payload files are readable by processes of your same UID, and the brief stays visible on the Claude process command line — never put secrets in a task file;
• this is a public beta, not a fleet scheduler: one session, one watcher, one audit at a time.

Prerequisites

• Linux — the tested real-host combination is Linux with Claude Code 2.1.208; other platforms and CLI versions are not verified and no broader claim is made;
• Python 3.12+ — the package has zero runtime dependencies (standard library only);
• tmux — launched sessions run inside a new tmux session;
• Claude Code CLI, installed and authenticated separately — this tool never ships, wraps, or configures it.

Install

Pre-PyPI beta — read before installing. fable-session 0.3.0b1 is not published on PyPI and the name is not yet owned there, so do NOT run an unqualified index install (nothing qualifies today, and a same-named package appearing later would be someone else's). Until package-index publication (a later, separate decision), install only from the tag-pinned GitHub source below or a GitHub release artifact — and these commands work only after the public v0.3.0-beta.1 tag exists in the official repository. Before then, install from a checkout as shown in the Quickstart.

Install into an isolated environment from the tag-pinned source:

# pipx (tag-pinned GitHub source)
pipx install "git+https://github.com/getaskclaw/fable-session@v0.3.0-beta.1"

# uv (tag-pinned GitHub source)
uv tool install "fable-session @ git+https://github.com/getaskclaw/fable-session@v0.3.0-beta.1"

# plain pip, isolated venv (tag-pinned GitHub source)
python3.12 -m venv ~/.venvs/fable-session
~/.venvs/fable-session/bin/pip install "fable-session @ git+https://github.com/getaskclaw/fable-session@v0.3.0-beta.1"

Alternatively, once the v0.3.0-beta.1 GitHub prerelease exists, download its attested wheel plus SHA256SUMS, verify the checksum, and install the wheel file directly.

Your first dry run (starts nothing)

A dry run is the default and launches nothing — it shows you exactly what would run and writes a run manifest:

fable-session run --project example-api --task /absolute/path/task.md --dry-run

Before this works you register your project once and add a small profile to your repository. The Quickstart walks your whole first session end to end: install, registry, profile, task file, dry run, launch, one watch, one audit.

The three commands

One console command, three subcommands — the whole lifecycle:

fable-session run   --project example-api --task /abs/task.md --launch --tmux api-example
fable-session watch --manifest /abs/runs/<run-id>/manifest.json --follow
fable-session audit --manifest /abs/runs/<run-id>/manifest.json

• fable-session run — resolve a registered project, build the bounded brief, construct the exact Claude CLI command, and (only with --launch) start it in a new tmux session;
• fable-session watch — follow exactly one launched session's structured JSONL stream, reporting lifecycle events (pauses and refusals included) without ever acting on the session, and exit by itself at the lane's terminal state;
• fable-session audit — after the watcher exits: prove from the session's own transcript which models actually served it.

Every option, guarantee, and edge case is specified in the Reference.

Privacy in short

Run manifests and command output carry hashes, byte sizes, and paths — never prompt text, credentials, or terminal history. Never put secrets in a task file: while a session runs, prompt material is readable by processes of your own user on the same host, and secret-shaped content is rejected before launch. The exact payload mechanism and its limits are documented in the Reference.

Documentation

• Quickstart — your first session, end to end: checkout, registry, profile, task, dry run, launch, watch, audit;
• Reference — the full lifecycle detail: configuration, run state, audit verdicts, watchdog events, privacy contract, migration from claude-context-tools, development, and release notes;
• Validation record — the privacy-safe evidence for the one real smoke and the deterministic release gates;
• Security policy — how to report a vulnerability (GitHub private vulnerability reporting only);
• examples/projects.toml — a commented registry example.

Status and license

fable-session is licensed under the MIT License — see LICENSE; package metadata says the same. The official home for this project is https://github.com/getaskclaw/fable-session — the repository is public, holds the independently reviewed clean history, and has GitHub private vulnerability reporting enabled and verified. The source-level public-beta gates in PUBLIC_RELEASE_CHECKLIST.md are complete; the v0.3.0-beta.1 GitHub prerelease does not exist yet — its tag is pushed only after the release-status PR merges and protected-main CI passes, and only a successful run of the tag workflow creates the prerelease. The ORIGINAL pre-export working history must never be pushed publicly. Security reports: see SECURITY.md.