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. Every launch materializes a new config dir from the template (settings + onboarding/trust flags + MCP servers) plus a copy of the freshest login, and hands it to Claude Code as CLAUDE_CONFIG_DIR. No transcripts, history or project trust carry over between sessions; ~/.claude is only the login holder (the refresh-rotated token is synced back to it on each launch). Finished dirs beyond keep_sessions (default 30) are pruned; live ones never are. Opt out per launch with AC_FRESH=0, globally with "fresh_session_per_launch": false in config.json, or by pre-setting CLAUDE_CONFIG_DIR yourself. Embedders (hugpy-station seats/keepers) pass AC_SETTINGS_JSON (a settings.json doc that replaces the template for that session) and AC_SESSION_LABEL (suffix on the dir name). The fresh .claude.json carries the login identity (oauthAccount/userID) from ~/.claude.json, trusts the launch cwd, and gives the toolserver MCP bridge the operator token when resolvable. An explicit --model in the pass-through args is honored as-is (no launcher model, no quota preflight). Wire it up with:

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

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 ....