small-scripts/FUTURE.md

Future Ideas

Script runner / installer

• Problem: Manually symlinking each script to ~/sbin is tedious
• Idea: A scripts/install.sh that symlinks all scripts in scripts/ to ~/sbin, with --dryrun support naturally
• Open questions: Should it handle removal of stale symlinks? Version checking?
• Depends on: Having at least 2-3 scripts to justify the automation

CI test runner

• Problem: Tests are only run manually
• Idea: Gitea CI action that runs tests/run-all.sh on push
• Open questions: What runner is available on Gitea? Docker-based?
• Depends on: Gitea CI being available (cluster-bootstrap M10)

claude-profile engagement modes — follow-up integration

The initial engagement mode picker (chat / quick / deep / hybrid / orch) ships with claude-profile and writes active-mode.env into the active profile directory. Several integration pieces are deferred to future work — none block v1 but each unlocks the design fully:

CLAUDE.md project picker integration

• Problem: claude-profile --project <name> writes CLAUDE_PROJECT into active-mode.env, but the existing CLAUDE.md session-start project picker still runs and ignores it. The user has to pick the same project twice when launching with a preset.
• Idea: Update ~/dev/claude/CLAUDE.md (the top-level session-start instructions) to read $CLAUDE_CONFIG_DIR/active-mode.env first; if CLAUDE_PROJECT is set, skip the interactive project menu and cd straight into that project. Same hook can announce the active mode to satisfy the "first message after /clear" templates in each mode file.
• Open questions: Does the CLAUDE.md flow have a clean place to read shell env files, or does claude-profile need to inject the project name into the appended system prompt directly? The latter is simpler but couples the picker to claude-profile.
• Depends on: Nothing blocking — can be done any time.

Status-line script: render the mode tag

• Problem: The mode tag (chat / quick / deep / hybrid / orch) is recorded in active-mode.env but the status line at ~/.claude/status/statusline.sh does not currently read it. Humans cannot see the active mode at a glance, which is the whole point of the persistent indicator.
• Idea: Update the status-line script to read $CLAUDE_CONFIG_DIR/active-mode.env, extract CLAUDE_MODE_TAG and CLAUDE_DRIVER, and prepend them to the existing topic in the format [Driver] mode-tag · topic | N% ctx. Modes with named subagent escalation (deep, hybrid) should render an arrow: [Sonnet→Opus] deep · topic. Orchestrator should append a queue-depth segment: [Sonnet] orch · project · queue:N.
• Open questions: Where does the status-line script live in the repo (it's outside small-scripts)? Should the queue-depth read be cached to avoid hammering .agent-tasks.json on every status-line render?
• Depends on: The status-line script is in claude-foundations, not small-scripts — this work happens in that repo.

bg-model-call wrapper

• Problem: The deep and hybrid modes both reference bg-model-call as the standardised way to fire a third-party model (MiniMax, etc.) in the background and have the result land in a sentinel file. The wrapper does not exist yet — modes currently just describe the pattern.
• Idea: A new small-script bg-model-call that takes a model name, a prompt file, and an output file; runs the appropriate container in the background; writes the result + a sentinel .done file when finished. Standardises timeouts, exit codes, and the sentinel format so ScheduleWakeup prompts can be self-contained.
• Open questions: Which third-party models do we actually want to wire up in v1 (MiniMax M2 only, or also others)? Where do API credentials live (secrets folder, with what naming)? Does the wrapper run via Docker on the local host, or via the agent-runtimes control plane?
• Depends on: Spec for the wrapper. This is its own small-scripts entry.

switch mode skill (mid-session re-pick)

• Problem: The mode is fixed at launch by claude-profile. Switching mid-session currently requires /clear + relaunch. For the common case "started in deep, this turned out to be trivial, drop to quick" there is no in-session path.
• Idea: A switch-mode skill (in custom-claude-skills) that re-runs the picker logic by writing a new active-mode.env, then asking the harness to apply it. The driver model can't actually swap mid-session (--model is launch-only), so the skill works by either (a) instructing the user to relaunch, or (b) updating the active-mode.env so the next /clear picks up the new mode without re-prompting. Option (b) is more useful in practice.
• Open questions: Should the skill be invoked by typing literal "switch mode" (matched by a UserPromptSubmit hook) or by a slash command /switch-mode? The mode files all assume the literal phrase.
• Depends on: No technical blockers; depends on someone actually wanting to switch modes, which may turn out to be rare in practice.

MiniMax-driven session with Claude container subagents (inverted architecture)

• Problem: The current claude-profile design assumes Claude Code is the main loop and Claude models are the driver. The cheapest available driver is Haiku (hybrid mode), which is still Anthropic-priced and still consumes Claude OAuth quota for every conversational turn. For long-running sessions where most turns are mundane routing and only occasional turns need real reasoning, the driver is the dominant cost. A non-Claude driver (MiniMax M2 specifically — comparable agentic ability at a fraction of the per-token cost, on a different vendor and quota pool) would unlock substantially cheaper long sessions while still letting us reach for Opus/Sonnet on demand via container subagents.
• Idea: A new launcher (working name: agent-profile or minimax-profile, parallel to claude-profile) that runs MiniMax as the conversational driver and treats Claude Code instances running inside containers as named subagents. The container subagents are dispatched via the existing agent-runtimes control plane — same infrastructure the orch mode already uses, just invoked from a different driver. Result-passing is file-based (already established as the right pattern in this session): the MiniMax driver writes a prompt file, fires a container, polls for a sentinel, reads the result file. No multi-megabyte tool-call payloads streaming through MiniMax's context window.

Architectural shape

1. Driver layer — a MiniMax agentic harness (either MiniMax's own CLI if one exists at the time, or a thin custom harness built on the MiniMax SDK with a tool-calling interface). This is not Claude Code; the existing CLAUDE.md / skills / hooks / status-line mechanisms do not apply directly. Some equivalents may need to be reimplemented or ported.
2. Subagent dispatch layer — a small set of tools the MiniMax driver can call: consult_opus(prompt_file, out_file), consult_sonnet(prompt_file, out_file), consult_minimax_self(...) (for parallel MiniMax thinking on the same machine). Each tool is a thin shim that submits a task to the agent-runtimes control plane and waits on a sentinel file, identical in shape to the bg-model-call wrapper described above.
3. Result passing — file-based, as in the rest of this design. The MiniMax driver never reads a multi-thousand-token Claude response into its own context unless it explicitly chooses to. Default flow: write prompt → fire container → wait → read summary line → optionally read full file.
4. Engagement modes (parallel set) — chat, quick, deep, hybrid, orch may or may not all map cleanly. hybrid (cheap driver, premium subagents) is the obvious fit and arguably the only mode that makes sense here — if you're not in hybrid you're either using a cheaper driver for trivial work (re-launch in chat) or wanting a Claude driver (use claude-profile). Worth designing as one mode rather than five.

Credential management — the load-bearing piece

This is where the user's explicit ask sits, and where it's easy to go wrong:

• MiniMax credentials for the driver: API key, lives at ~/dev/claude/secrets/minimax/api_key (proposed; user to confirm naming). Read by the MiniMax driver process at launch only. Never written into a container, never logged, never put on a command line (use stdin or env-var injection at exec time).
• Claude credentials for container subagents: the existing ~/dev/claude/secrets/claude/long_lived_oauth_token (per cross-project memory) — already used by agent-runtimes containers via CLAUDE_CODE_OAUTH_TOKEN. No change needed; the containers already know how to read it.
• Strict separation: the MiniMax driver process must NOT have access to the Claude OAuth token. The containers must NOT have access to the MiniMax key. Each side reads only its own credential file at point of use. This rules out a "load all secrets into env at launch" pattern.
• No credential crosses to subprocess args. MiniMax key into the driver via env or stdin only. Claude OAuth into the container via the existing agent-runtimes mechanism (volume mount or env var, set by the control plane, not by the driver process).
• Audit boundary: if the MiniMax driver ever needs to be told "run a Claude container," it asks the control plane to do it. The driver does not invoke docker run directly. This keeps the credential boundary at the control plane, where it already exists, rather than moving it into the driver.
• Cross-project memory feedback already covers this: "Stream secrets from files" — read tokens from source files at point of use; never reconstruct from context. Apply that same rule to both credential pools.

Open questions

1. Does MiniMax M2 ship a usable agentic CLI/harness in 2026? If yes, how mature — does it have tool-calling, file editing, persistent context, hooks? If no, the work is "build a minimal agentic harness" first, which is a significant project on its own.
2. Tool-call interop: MiniMax's function-calling format vs. Claude Code's tool-result format. If we want a Claude container to be able to surface useful structured data back, the driver needs to translate. File-passing avoids most of this — JSON/markdown files are vendor-neutral.
3. Where does this launcher live? Same small-scripts repo, or its own project? Lean toward small-scripts initially; promote to its own project once it has its own modes/specs/tests at a similar scale to claude-profile.
4. Status line / WezTerm theming: Currently driven by claude-profile's WezTerm escape sequences. The MiniMax driver runs in the same terminal — does it reuse that theming, or pick its own colour to make the inverted-architecture session visually distinct?
5. Does this replace hybrid mode entirely, or coexist? hybrid (Claude Haiku driver) is a strict superset functionally — same tools, same Claude harness — but more expensive than MiniMax. Some users may prefer staying inside Claude's harness even at higher cost; others may want the MiniMax surface for cost reasons. Likely coexist.
6. Failure modes when the MiniMax API is degraded: Claude Code has decent retry/backoff. A custom MiniMax driver needs the same — and a clean way to fall back to a local model or to claude-profile --mode hybrid if MiniMax is unreachable for a sustained period.
7. Subagent quota economics: if every container subagent burns Claude OAuth quota, and the driver burns MiniMax quota, are we actually saving money? Sketch out a typical-session token budget under both architectures (claude-profile hybrid vs. minimax-profile) before committing — this might be the kind of "feels cheaper but isn't" optimisation that wastes a weekend.

Depends on

• MiniMax M2 maturity — specifically whether an agentic harness exists or needs building. Worth re-checking every few months.
• agent-runtimes control plane — already exists and is actively used; no new infrastructure required there, but the control plane needs a small documented contract for "submit a Claude consult task and return the result file path."
• The bg-model-call wrapper from this same FUTURE.md section — if that ships first, the subagent dispatch layer here is mostly already built; this entry becomes "new driver harness on top of an existing wrapper."
• A token-budget sketch — before any code is written, estimate a 4-hour session under both architectures with realistic ratios of routine vs. reasoning turns. If the savings are <30%, this is a research project, not a productivity win.