AI integration
aims can tell Claude Code and Codex which accounts exist and let them act on it: switch the account for new sessions, fail over when this one hits its limit, or hand a self-contained task to another account right now.
aims setup --all # everything below, and the login keepalive
aims setup # skill and MCP server only
aims clean # take it all back outaims init offers the same choices. Restart running sessions afterwards.
MCP server
aims mcp is an MCP server over stdio. aims setup registers it as a user-level server named aims: with claude mcp add in every Claude Code login (each login keeps its own list), and in the shared config.toml for Codex.
Codex starts MCP servers with only a few variables (HOME, PATH and the like) and stops waiting for a tool after 60 seconds. So the Codex entry also lists the variables aims reads (env_vars: the session’s account, pins, AIMS_HOME and so on) and waits up to an hour (tool_timeout_sec). Running codex mcp add aims yourself drops both; aims doctor notices, and aims setup puts them back. Codex may also keep MCP tools out of the model’s first view and let it find them when needed; the skill tells it to look for mcp__aims__*.
| Tool | What it does |
|---|---|
aims_status | Every account with its login, plan usage and marks, and which account this session runs as. live: true asks the providers first. |
aims_switch | Make a profile the one new sessions start on in this project (the git repository or folder the session runs in), for one tool or every tool that has it; global for every folder. |
aims_failover | This account hit its limit or lost its login: mark it, so new sessions use the next one (until it works again). With to, that profile comes first in this project (global: every folder). Answers with the command that continues the conversation there. |
aims_clear | Remove marks from one profile or all of a tool’s profiles. |
aims_move | Move this session’s conversation to another account once the current turn ends (only in a session that moves by itself). |
aims_run | Run a prompt now with another account (claude -p or codex exec), with the same retry rules as the CLI. Returns the final answer. Read-only unless the call sets write. Gives up after 10 minutes, or timeoutSeconds (at most an hour). |
aims_login_help | The command a person must run to log a profile in. The model cannot complete a browser login, and does not try. |
A session started with aims claude or aims codex (no @profile) moves on by itself at a limit; the model has nothing to do, and aims_move moves it on purpose. In such a session aims_failover moves the conversation too. Any other running session cannot change its own login, so the model tells you to restart (aims claude --continue) instead of pretending it switched. Each session started through aims carries AIMS_SESSION_PROFILE (for example claude:work), which aims_status reports and aims_failover uses as the account to mark.
By default, aims_run requests the upstream CLI’s restrictive mode: Claude Code’s plan mode or Codex’s read-only sandbox. These are the installed CLI’s permission controls; aims does not add operating-system isolation. With write: true the run gets your normal settings, which for a headless Claude Code run still excludes anything that would ask for approval. Review your MCP client’s approval settings for this tool, including the write argument: aims does not enforce the client’s approval policy. A run started this way cannot start another aims_run, and when the MCP client disconnects, aims stops any run it started.
Individual MCP request cancellation is also passed to headless workers and live probes. A canceled live-status check stops before probing the next profile and does not replace cached account state with a canceled result. The server remains available for other requests.
Before setup, refresh or removal changes an MCP registration, aims retains a private recovery copy of its settings under ~/.aims/recovery/mcp (or $AIMS_HOME/recovery/mcp). Unchanged contents reuse the same copy. A registration failure names the recovery path; compare it with the current settings before restoring anything, because another tool may have edited them meanwhile. These settings may include inline MCP secrets, so keep recovery files private. Login credential files and keychain entries are not backed up or moved by this mechanism.
Skill
aims setup writes skills/aims/SKILL.md into ~/.claude and ~/.codex (and into profiles that keep skills private through share: none or exclude). It teaches the model when to use the MCP tools (a limit error, a dead login, “which account am I on?”) and the rules around them: never copy login files, and never move one account’s data to another unasked.
Skill updates preserve previous text in a private .aims-skill-*.bak beside the installed aims skill directory. Externally managed symlinks are left to their owner; uninstall recognizes previously bundled skill versions and keeps edited skills, backups and user additions. Automatic pre-session refresh shares the profile lifecycle lock with setup, logout, purge and clean, so an integration write cannot recreate a home after its removal transaction. aims doctor --check diagnoses stale skills and MCP settings without running a provider. Use the indicated setup command to update those integrations deliberately.
Claude Code plugin
Instead of aims setup, Claude Code users can install the MCP server and skill as a plugin. aims itself must be installed and on your PATH:
/plugin marketplace add doguyilmaz/aims
/plugin install aims@aimsUse one or the other. With both, the model sees the tools twice.
Status line
aims setup --statusline sets aims as Claude Code’s status line command. It shows the account of the running session and its plan usage in a few characters:
~/src/app main work ▰▱▱▱▱ 11% · 7d 47%
~/src/app main work ▰▰▰▰▱ 82% ↻1h20m · 7d 61%
~/src/app main work ▰▰▰▰▰ 97% ↻54m · 7d 61% → personalThe bar is the five-hour window, then the weekly one. Numbers turn yellow at 70% and red at the threshold; from 70% on, ↻ says when the window resets. Past the threshold, or when the account is marked as limited, → names the account new sessions get instead. The running session keeps its account; aims moves a supervised session by itself, and aims failover claude --resume continues any other conversation on the next account (see In an interactive session).
The usage numbers come from Claude Code itself, which passes them to the status line command. aims records them, which is how it knows to skip an account before the limit hits, at no cost.
If you already had a status line command, aims keeps it: your line is shown first, followed by aims’ part. aims clean puts your command back.