The built-in terminal

That Claude Code session can run inside AI-POS. On the project’s Terminal page, click the entry you want (an agent CLI, or a plain Shell — anything not installed is greyed out) and it runs in the project root. The experience is identical to an external terminal: login, slash commands, and permission prompts all belong to the CLI itself.

Which CLIs auto-connect to the hub

Because the CLI runs in the workspace root, the Claude CLI picks up .mcp.json and connects to the hub automatically. Other vendors’ CLIs wire up MCP differently, so they do not connect automatically — consult your CLI’s own MCP documentation to point it at aipos-mcp.

A few things worth knowing:

Multiple sessions side by side

One project can have several tabs open. The tab bar is keyboard-operable — Tab into it, then use left/right arrow keys to switch tabs (Home/End jump to the ends).

Switching projects doesn’t interrupt anything

Sessions belong to the app, not to the page. Switch to another project and come back: the screen replays and you keep typing. The sidebar’s “Terminal” item and the project card show a “terminal running” marker, and the app-level Agent sessions page lists sessions across every project with one-click return.

Only you can start one

AI-POS never opens a terminal on its own and never types anything on your behalf. Account credentials are managed by each CLI (AI-POS doesn’t touch them).

Closing the app terminates running processes

You get a confirmation prompt first. Next time you open the app, terminals that can be resumed come back as restored tabs. The previous screen contents are not preserved, but whichever restored tab you switch to reconnects automatically: it reloads the last conversation using that agent’s resume flag (Claude Code’s --continue, the equivalent for Codex and Gemini) and becomes typeable again without you pressing anything — and it prioritises the tab you were last using. If reconnection fails (the CLI isn’t installed, no network) you get a retry/close card rather than an endless retry loop. Terminals that cannot be resumed — custom CLIs and the plain shell — are not restored and vanish when the app closes. Just close any restored tab you don’t need.

Pop-out windows

A running tab has a small pop out icon. Pressing it moves that terminal into a separate OS window — drag it to a second monitor, or put it side by side with the Tasks page. The slot in the main window becomes a “popped out” placeholder; press Dock back, or close the separate window, to return it. (With a pop-out open, closing the main window closes the whole app.)

Managing the launcher list

The list of launchable entries is managed at the app level under Settings → Agent CLI. Presets are Claude Code, Codex CLI, and Gemini CLI, plus a plain Shell (chosen per platform: PowerShell 7 if installed, otherwise Windows PowerShell; your login $SHELL on macOS/Linux, falling back to /bin/sh). You can add custom agents too — name, command, arguments, and environment variables.

Local LLM endpoints

A custom CLI’s environment variables field takes one KEY=value per line, passed to the CLI at launch. To point an agent at a local model, aim its base URL there — Claude Code’s ANTHROPIC_BASE_URL, or OPENAI_BASE_URL for OpenAI/Codex-style tools, pointed at Ollama (/v1), LM Studio, vLLM, or similar. Or just add ollama itself as a custom CLI (command ollama, arguments run <model>) and talk to a local model straight from the terminal.

Caution

These variables are stored in plaintext in ~/.aipos/agents.json. Placeholder values a local endpoint asks for are fine here; real cloud credentials are not — those belong to the CLI’s own sign-in.

What is and isn’t recorded

Terminal screen contents are never written to the ledger or the search index. What the agent does to the project (creating tasks, recording decisions) still leaves a trace, because that goes through the hub tools.