abstract-claude

Fresh Claude Code session manager: a settings-only template, durable OAuth, automatic quota fallback, and a web console — packaged as one pip-installable CLI.

Install

pip install abstract-claude                 # from your index
# or from the private index:
pip install -i https://<index>/api/pypi/simple/ abstract-claude

Quickstart

abstract-claude init                        # materialize AC_ROOT (config + template)
abstract-claude serve                       # web console (default http://127.0.0.1:9111)
sudo abstract-claude install-service        # install + enable the systemd unit

Commands

Tool-aware sessions (MCP)

abstract-claude mcp discovers a toolserver's /endpoints and serves them to Claude Code over stdio MCP — so the .claude session can call the whole abstract_* tool surface (and /claude/*) through one authed entry point. The template registers it automatically; to add it to an existing install:

claude mcp add -s user toolserver -e TOOLSERVER_URL=https://toolserver.hugpy.ai -- abstract-claude mcp

How it works

• Template = config only. template/settings.json + a minimal ~/.claude.json (onboarding/trust flags). No credentials, history, or transcripts — a reset gives a genuinely clean session, not a restored snapshot.
• OAuth is not templated. Login rides on the durable 1-year CLAUDE_CODE_OAUTH_TOKEN (managed by claude-auth), so a fresh session auto-authenticates — no /login.
• Quota fallback is the wrapper. Claude Code's fallbackModel only fires on overload, never on quota; autoContinueAtUsageLimit doesn't exist before v2.1.234. abstract-claude launch handles the real case: default Fable maxed → run on Opus 4.8.
• Fresh .claude per launch — no memory. Every launch DELETES ~/.claude and ~/.claude.json and rebuilds them with only the template settings (or the embedder's AC_SETTINGS_JSON), fresh onboarding/trust flags + MCP servers, and the login (freshest credentials + oauthAccount/userID identity). Transcripts, history, todos, project trust and caches from earlier sessions are gone; the launch cwd is trusted. config.json fresh_session_mode: wipe (default), dir (keep ~/.claude, use a new ~/.claude-sessions/<stamp>-<pid> via CLAUDE_CONFIG_DIR; sessions [--prune] lists), or off. AC_FRESH=0 or a pre-set CLAUDE_CONFIG_DIR skips it for one launch. An explicit --model in the pass-through args is honored as-is (no launcher model, no quota preflight). abstract-claude mct does the same at REPL start and additionally forgets the persisted session.json id, so A opens a brand-new claude session each launch.
• Claude-Code-style input for mct. The prompt box stays at the bottom of the terminal (prompt_toolkit); A's activity and the rendered turn scroll above it and a status bar under it shows spinner · turn · elapsed · pending queries. Multi-line input is one prompt: Enter sends, \+Enter / Alt+Enter / Ctrl-J / Shift+Enter add a line, bracketed paste keeps newlines, first Ctrl-C clears the box. --plain, no TTY, or a missing prompt_toolkit fall back to the readline line loop. Wire it up with:

  alias claude='abstract-claude launch --dangerously-skip-permissions'
  

• A's system prompt is recorded. mct runs A with --system-prompt-snapshot on, so Claude Code writes the FULL system prompt (built-in text + memory + this seat's appended directive) as a prompt_snapshot record in the session transcript (~/.claude/projects/<cwd-slug>/<session>.jsonl). Watch every session on the host live with sysprompt-watch (--once for the current state, --full, --diff). Claude Code reuses the recorded prompt on --resume, so an edited operator-guidance.md applies at the next /new / relaunch (the REPL says so). AC_SYSPROMPT_SNAPSHOT=0 turns the recording off.

Config

AC_ROOT (default /srv/abstract_claude) holds config.json:

{ "listen_host": "127.0.0.1", "listen_port": 9111,
  "default_model": "claude-fable-5[1m]", "quota_fallback_model": "claude-opus-4-8",
  "preflight_quota_check": true }

Override the data root with AC_ROOT=/path abstract-claude ....