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.

Part of the hugpy orbit

                    ┌──────────────────────────── hugpy (fleet) ───────────────────────────┐
                    │ central + workers: platform · engine · fleet · server · media · …     │
                    │ OpenAI-compatible /v1 — every local model, incl. B (Qwen3-Coder-Next) │
                    └───────▲───────────────────────▲──────────────────────────▲───────────┘
                            │ inference             │ inference                │ B reductions
   ┌────────────────────────┴──┐   ┌────────────────┴──────────┐   ┌───────────┴───────────────┐
   │ hugpy-station             │   │ hugpy-agent               │   │ abstract-toolserver       │
   │ desktop + headless console│──▶│ agent runtime · TUI ·     │◀─▶│ comms · ledgers · boards ·│
   │ tmux seats per locus      │   │ OpenCode/qwen seats       │   │ exchanges · MCP · b_ask   │
   └────────────┬──────────────┘   └────────────┬──────────────┘   └───────────▲───────────────┘
                │ keeper/codex seats            │ --serve                      │ tools (MCP/HTTP)
   ┌────────────▼──────────────┐   ┌────────────▼──────────────┐               │
   │ abstract-gpt (Codex seat) │   │ abstract-claude serve ────┼───────────────┘
   │ abstract-claude (Claude)  │   │  └ abstract-serve-core    │
   └───────────────────────────┘   └───────────────────────────┘
          everything ships through abstract-pypit → PyPI (+ GitHub)

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-opus-4-8", "quota_fallback_model": "claude-opus-4-8",
  "preflight_quota_check": true }

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

Serve, roles and launch (0.1.68 – 0.1.96)

• abstract-claude serve runs the shared routes in abstract_serve_core/console/server.py. See the serve-core README for roles, relay, queue and interrupt behaviour.
• Launch contract: session-first launch, managed rollover (handoff → /clear → resume through the toolserver ledger), TUI harness, and a reuse gate before an existing session is attached.
• Claude launch and seat reporting live in processes/, lifecycle hooks in hooks/, and the headless REPL in mct/. Shared model, accounting, and console implementations are imported directly from abstract_serve_core.

Attention-worthy

• Versions are bumped by abstract-pypit on publish; don't hand-edit them.
• Same-version republish needs pip install --force-reinstall.

Python package layout

The package root holds its CLI entry points, version, and packaged assets. Implementations are grouped by responsibility:

Import implementations directly from these subpackages. The former flat module aliases have been removed; shared Claude and GPT helpers live in abstract_serve_core and callers import them there. Console provider discovery continues to use the abstract_serve_core.providers metadata group, with targets in abstract_serve_core.console.providers.