augint-shell

augint-shell is a Python 3.12+ command-line tool (the ai-shell command) that launches AI coding tools (Claude Code, Codex, opencode) and local LLMs (Ollama, Open WebUI, Kokoro TTS, Speaches STT) in per-project Docker containers. It is built on Click for the CLI and the Docker SDK for Python to build and orchestrate those containers. As a library/CLI it runs no servers of its own: releases are published automatically to PyPI (augint-shell) and Docker Hub (svange/augint-shell).

Pipeline Artifacts

Reports are published to GitHub Pages on every push to main.

Report	Link
API docs	svange.github.io/augint-shell/ai_shell.html
Test coverage	svange.github.io/augint-shell/coverage/htmlcov/
Test results	svange.github.io/augint-shell/coverage/test-report.html
Security scans	svange.github.io/augint-shell/security/
License compliance	svange.github.io/augint-shell/compliance/
PyPI package	pypi.org/project/augint-shell/

Documentation

Document	What's inside
CLAUDE.md	Architecture -- dependency flow, the two container categories, config/env layering, mount assembly, and the scaffold system. Primary guidance for Claude Code.
AGENTS.md	Agent & contributor rules -- project layout, build/test commands, coding style, testing, and commit/PR conventions.
TMUX.md	Runbook for `ai-shell claude --multi` -- multi-pane tmux running Claude Code across several repos in one container.
CHANGELOG.md	Release history, generated by Python Semantic Release from Conventional Commits.
LICENSE	License terms.

Release & Branch Model

augint-shell is a library/CLI: it has no staging or production servers. Instead of deploy environments, git refs map to publish targets, and releasing is fully automated -- there is no manual deploy step.

Git ref	Pipeline runs	Publishes to
Feature branch -> PR to `main`	Code quality, security scans, license compliance, unit tests, build validation	Nothing (validation only)
Push / merge to `main`	All of the above, then Python Semantic Release cuts a version when Conventional Commits warrant one	PyPI, Docker Hub, and the Pipeline Artifacts reports on GitHub Pages

The single deploy environment is the GitHub Actions pypi environment (trusted publishing via OIDC -- no stored PyPI token). The Docker image also rebuilds when files under docker/ change, independent of a version bump. Full pipeline: .github/workflows/publish.yaml.

What This Does

ai-shell is a Python CLI that stands up:

Per-project dev containers (augint-shell-{project}-dev) -- one per repo, runs Claude Code, Codex, opencode, or aider with your project mounted, SSH keys, AWS creds, and tool configs wired in.
Host-level LLM stack (shared singletons) -- Ollama, Open WebUI, Kokoro TTS, Speaches STT, a Pipecat voice agent, and n8n on a common Docker network. GPU auto-detected.

One command replaces the old Makefile + docker-compose.yml workflow.

Getting Started

This project uses AI-assisted development. You do not need to memorize git commands or CI configuration -- your AI agent handles that.

Prerequisites

Docker
Python >= 3.12
(Optional) NVIDIA GPU + drivers for local LLM acceleration

First-time setup

pip install augint-shell
# or:  uv add --dev augint-shell

Running locally

# Launch Claude Code in the current project
ai-shell claude

# Launch with extra args
ai-shell claude -- --debug

# Set up local LLM stack (first time)
ai-shell llm setup

# Launch opencode with local LLM
ai-shell opencode

How to Contribute

Contributions are made through AI agents (Claude Code, Copilot, etc.). You describe what you want changed in plain language; the agent handles branching, coding, testing, and submitting a pull request.

Open Claude Code (or your AI agent) in this repo.
Describe the change you want -- a bug fix, a new feature, a doc update.
The agent will:
- Create a feature branch
- Make the changes
- Run pre-commit checks and tests
- Open a pull request
Review the PR when the agent is done. CI runs automatically.
Merge once CI is green.

If you need to work manually, see the full contributor guide (if available).

Commands

AI Tools

Command	Description
`ai-shell claude`	Launch Claude Code
`ai-shell claude-x`	Claude Code with skip-permissions
`ai-shell codex`	Launch Codex
`ai-shell opencode`	Launch opencode (TUI)
`ai-shell opencode --web`	Launch opencode web UI with mDNS + CORS
`ai-shell opencode serve`	Headless server + attach all git repos as terminals
`ai-shell opencode status`	Show server URL, mDNS name, attached terminals
`ai-shell shell [bash\|zsh\|fish]`	Interactive shell in dev container
`ai-shell <tool> --t3`	Also expose the project to T3 Code (phone/desktop app)
`ai-shell <tool> --expo`	Also start a tunnelled Expo dev server and print its QR code

LLM Stack

Command	Description
`ai-shell llm up`	Start Ollama (add `--webui`, `--whisper`, `--voice-agent`, `--n8n`, `--image-gen`, or `--all`)
`ai-shell llm down`	Stop LLM stack
`ai-shell llm pull`	Pull configured models
`ai-shell llm models`	Browse curated model catalog
`ai-shell llm unload [MODEL]`	Unload models from VRAM
`ai-shell llm setup`	First-time setup (up + pull + configure)
`ai-shell llm status`	Show status and available models
`ai-shell llm logs`	Tail LLM stack logs
`ai-shell llm shell`	Shell into Ollama container

Container Management

Command	Description
`ai-shell manage status`	Show dev container status
`ai-shell manage stop`	Stop dev container
`ai-shell manage clean`	Remove container and volumes
`ai-shell manage logs`	Tail dev container logs
`ai-shell manage pull`	Pull latest Docker image
`ai-shell manage env [--aws]`	Show resolved environment variables

Configuration

Optional .ai-shell.yaml in your project root (YAML default, TOML also accepted). Run ai-shell init for the full template.

container:
  image: svange/augint-shell
  image_tag: latest
  extra_env:
    MY_VAR: value
  dev_ports: [3000, 4200, 5000, 5173, 5678, 8000, 8080, 8888]
  extra_ports: []

openai:
  profile: work  # resolves OPENAI_API_KEY_WORK from .env

claude:
  account: work  # resolves CLAUDE_CODE_OAUTH_TOKEN_WORK from .env

expo:
  auto: true  # start a detected Expo app automatically (--expo/--no-expo override)

llm:
  primary_chat_model: qwen3.5:27b
  secondary_chat_model: huihui_ai/qwen3.5-abliterated:27b
  primary_coding_model: qwen3-coder:30b-a3b-q4_K_M
  secondary_coding_model: huihui_ai/qwen3-coder-abliterated:30b-a3b-instruct-q4_K_M
  context_size: 32768
  ollama_port: 11434
  webui_port: 3000
  comfyui_port: 8188
  extra_models: []

Global config at ~/.ai-shell.yaml or ~/.config/ai-shell/config.yaml also supported.

Launch-time caches

To keep tool launches fast, two preflight checks are cached on the host under ~/.cache/ai-shell/:

Cache	Default TTL	What it skips
`image-pull`	15 min	`docker pull` of the `latest` image to compare digests (network round-trip)
`bedrock-check`	24 h	Bedrock `converse` preflight that verifies AWS auth + model access

Tune via YAML or env vars:

container:
  image_pull_cache_ttl: 900       # seconds (0 = always pull)
aws:
  bedrock_check_cache_ttl: 86400  # seconds (0 = always verify)

Equivalent env vars: AI_SHELL_IMAGE_PULL_CACHE_TTL, AI_SHELL_BEDROCK_CHECK_CACHE_TTL. Delete the corresponding file under ~/.cache/ai-shell/ to force a recheck on the next launch.

Local LLM stack

Four role-specific model slots, each sized for an RTX 4090 (24 GiB VRAM). All four defaults together total ~74 GB on disk.

Slot	Default	Size	Role	Routed to
`primary_chat_model`	`qwen3.5:27b`	17 GB	Best chat model that fits a 4090	Open WebUI default
`secondary_chat_model`	`huihui_ai/qwen3.5-abliterated:27b`	17 GB	Best uncensored chat (abliterated Qwen3.5)	Open WebUI (selectable)
`primary_coding_model`	`qwen3-coder:30b-a3b-q4_K_M`	19 GB	Best agentic coder with explicit Ollama tools badge	opencode / aider default
`secondary_coding_model`	`huihui_ai/qwen3-coder-abliterated:30b-a3b-instruct-q4_K_M`	19 GB	Best uncensored coder	opencode (selectable)

Optional stacks (not auto-started; opt-in with ai-shell llm up --<flag> or --all):

Flag	Service	Port	Notes
`--webui`	Open WebUI	3000	Implies `--voice` so Kokoro is wired as "read aloud" backend. Use `--no-voice` to skip.
`--voice`	Kokoro TTS	8880	OpenAI-compatible `/v1/audio/speech`
`--whisper`	Speaches STT	8001	OpenAI-compatible `/v1/audio/transcriptions`. GPU image auto-used when NVIDIA is detected
`--voice-agent`	Pipecat voice agent	8010	Push-to-talk PWA (Speaches -> Ollama -> Kokoro). See `VOICE_AGENT_PLAN.md`
`--image-gen`	ComfyUI	8188	GPU image generation. Wires into WebUI when combined with `--webui`
`--n8n`	n8n	5678	Workflow automation

OpenAI multi-account switching (`--openai-profile`)

Codex and opencode support switching between multiple OpenAI accounts via named profiles in .env:

# .env
OPENAI_API_KEY_WORK=sk-proj-...
OPENAI_ORG_ID_WORK=org-...
OPENAI_API_KEY_PERSONAL=sk-proj-...

ai-shell codex --openai-profile work
ai-shell opencode --openai-profile personal

Set a default in config (openai.profile: work) or via AI_SHELL_OPENAI_PROFILE=work.

Claude Code multi-account switching (`--account`)

ai-shell claude can use a different Claude account for each launch. Each account is an OAuth token in ~/.augint/.env. Get a token with claude setup-token while you are logged in to that account.

# ~/.augint/.env
CLAUDE_CODE_OAUTH_TOKEN_WORK=sk-ant-oat01-...
CLAUDE_CODE_OAUTH_TOKEN_CLIENT=sk-ant-oat01-...

ai-shell claude --account work     # use CLAUDE_CODE_OAUTH_TOKEN_WORK
ai-shell claude --account          # list the accounts (tokens are not shown)
ai-shell claude --account default  # use the ~/.claude login
ai-shell claude                    # use the configured account, else the ~/.claude login

The account name is the variable suffix, case-insensitive. A - in the name maps to _.

Set a default for a project in .ai-shell.yaml (claude.account: work) or with AI_SHELL_CLAUDE_ACCOUNT=work. Use --account default to override it for one launch.

Rules:

The selected token is injected as CLAUDE_CODE_OAUTH_TOKEN for the Claude process only. The other CLAUDE_CODE_OAUTH_TOKEN_* values are never passed into containers.
ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are removed from the Claude process, because Claude Code prefers them over the OAuth token.
An unknown account name, or an account together with --aws, stops the launch with an error.
All accounts share ~/.claude (settings and history). claude -c can continue a conversation that started under a different account.
--multi and --interactive set the token on the tmux session. Reconnecting to an existing tmux session keeps the account that started it.

Attaching to Windows Chrome (`--local-chrome`)

ai-shell claude --local-chrome bridges Claude inside the container to your real Chrome on Windows via the Chrome DevTools Protocol (using chrome-devtools-mcp). Unblocks OAuth popups, CAPTCHA pages, and "click around in a logged-in site" tasks.

Claude drives Chrome tabs on your Windows desktop in real time.
Separate Chrome profile per project -- your normal browsing untouched, each repo keeps its own logged-in state.
All traffic stays on localhost.

Set [claude] local_chrome = true in ai-shell.toml (or AI_SHELL_LOCAL_CHROME=1) to persist.

Remote control with T3 Code (`--t3`)

T3 Code is a desktop/web/mobile GUI for driving coding agents. Its server owns the workspace — it spawns the agent processes, reads git state and hosts terminals — so it has to run where the project lives, which for ai-shell is the per-project dev container. That is what --t3 sets up:

ai-shell claude --t3        # Claude in this terminal + T3 Code server for the project
ai-shell codex --t3
ai-shell pi --t3
ai-shell opencode --t3
ai-shell shell --t3         # Just the server, no tool

Each run:

installs the t3 CLI in the container if the image predates T3 support;
starts t3 serve --host 0.0.0.0 --port 3773 detached, with the same environment your tools get;
registers the project (t3 serve deliberately does not auto-add its cwd, which is why an unprepared server shows an empty environment);
mints a pairing token and prints a pairing URL + QR pointing at this machine's LAN address and the container's published host port.

Scan the QR from the T3 Code phone app, or paste the URL into the desktop app. The server keeps running after the local tool exits — that is the point.

Port 3773 is part of the standard dev-port set, so every dev container publishes it on a stable per-project host port. Containers created before this feature don't have that mapping; --t3 says so and the fix is ai-shell manage clean, then rerun.

T3 Connect (outside your LAN)

LAN pairing needs the phone on the same network. For anywhere-access, link the container once — the credential lives in the project's ~/.t3 volume, so it survives container recreation:

ai-shell shell
t3 connect link --headless      # prints a URL, paste back the code
exit
ai-shell claude --t3            # serve now also brings up the managed tunnel

--t3 reports T3 Connect status on every run.

What `--t3` is and isn't

T3 Code runs its own agent processes; it does not mirror the Claude session in your terminal. Both live in the same container against the same project and the same ~/.claude config, so a conversation started in one can be resumed in the other — but they are separate processes.

Each project gets its own T3 environment (its own ~/.t3 named volume: server database, paired devices, Connect credential). The host's own ~/.t3 is never bind-mounted, so a desktop T3 Code install and the container servers never share a database.

Expo apps (`--expo`)

Expo apps get their dev server started inside the dev container, with the tunnel URL printed as a QR code before the agent takes the terminal — so you scan once, up front, and the phone stays attached for the whole session.

ai-shell claude              # auto-detected: Expo app -> dev server starts too
ai-shell claude --expo       # force it (and fail loudly if it can't start)
ai-shell claude --no-expo    # skip it

Expo
  Project: my-app (/root/projects/my-app)
  Scan:    exp://Xf3k2a-anonymous-8081.exp.direct
  Metro:   http://localhost:14631 (this machine)
  Log:     docker exec augint-shell-my-app-dev tail -f /var/log/ai-shell/expo-start.log

  <QR code>

The server is detached and outlives the tool session. Re-running any command just re-prints the QR against the live server.

No Expo account needed

expo start --tunnel does not require a login. The Expo CLI connects with its own ngrok token and names the tunnel {randomness}-{username}-{port}.exp.direct, falling back to anonymous when nobody is signed in. Logging in only matters for EAS (build, update, submit).

If you do want to be signed in, the practical options in a container are npx expo login (persisted in ~/.expo, which is bind-mounted) or an EXPO_TOKEN personal access token. Browser SSO does not work in the container: it binds a callback listener on an ephemeral container port and shells out to a browser that isn't there. A robot EXPO_TOKEN is worse than none here — the Expo CLI refuses to open a tunnel for robot users, and ai-shell reports that specifically if it happens.

Why tunnel, and not LAN

ngrok dials outbound from the container, so the phone reaches https://<subdomain>.exp.direct with no published port involved. LAN mode cannot work as-is: ai-shell hash-assigns dev ports into 10000-39999 rather than mapping them identity, so Metro would advertise its own :8081 and the phone would find nothing there. Port 8081 is published anyway, so a host browser can reach Metro and expo start --web.

The QR is stable across restarts: Expo persists the tunnel's random segment in .expo/settings.json inside the project directory, which is bind-mounted.

Detection

Auto-start requires both an expo dependency in package.json and an app config (app.json with an expo key, or app.config.{ts,js,mjs,cjs,json}). A dependency alone also describes Expo libraries and config plugins, which have nothing to serve. --expo needs only the dependency.

ai-shell shell never auto-starts Expo — it is the maintenance path, often where you go to fix an install — but ai-shell shell --expo works. Set expo.auto: false in .ai-shell.yaml (or AI_SHELL_EXPO_AUTO=0) to turn auto-detection off for a project.

Dependencies are checked inside the container, because node_modules is a container-local named volume: a host-side npm install is invisible there. If Expo isn't installed in the container, auto-detection says so and steps aside rather than triggering an install.

OpenCode web mode

Browser UI

ai-shell opencode --web                # Launches web UI, opens browser
ai-shell opencode --web --port 8080    # Custom port

mDNS is enabled by default -- the server is discoverable on your LAN as <project>.local. CORS is set to * for cross-device access (phone, tablet).

Headless server with multi-repo terminals

ai-shell opencode serve                # Start server + attach all git repos under CWD
ai-shell opencode serve --skip-root    # Don't attach CWD itself
ai-shell opencode serve --open         # Auto-open browser after starting

serve finds all immediate child directories that are git repositories and attaches each as a terminal to the running server via opencode attach. The current directory is also attached by default (if it's a git repo).

Status dashboard

ai-shell opencode status               # Show server URL, mDNS name, terminal count

Authentication

Set OPENCODE_SERVER_PASSWORD (and optionally OPENCODE_SERVER_USERNAME) in your project .env file. These are automatically passed through to the container.

# .env
OPENCODE_SERVER_PASSWORD=mysecret
OPENCODE_SERVER_USERNAME=admin

Requirements

Docker
Python >= 3.12
(Optional) NVIDIA GPU for local LLM acceleration

Release files for augint-shell 0.109.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for augint-shell 0.109.0
File	Size	Uploaded
augint_shell-0.109.0.tar.gz	105.3 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for augint-shell 0.109.0
File	Interpreter	ABI	Platform	Reset
augint_shell-0.109.0-py3-none-any.whl 121.6 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 226.9 kB

Release files / augint_shell-0.109.0.tar.gz

Download URL	augint_shell-0.109.0.tar.gz
Size	105.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`35eaa0da36304e43a0514becedf5862a3a74f3523df1a2463dd6b30b009ea9e5`
BLAKE2b-256 checksum How to use checksums	`8e5c146cf068155818b1eeeb012e6660e362ab15bdc5010c28ef5b94532b72ee`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/svange/augint-shell
Publishing commit: github.com/svange/augint-shell/tree/f2ed6a16b0ba7c5017581b9aa96245a2dec095d5

Workflow

Publishing configuration: github.com/svange/augint-shell/blob/f2ed6a16b0ba7c5017581b9aa96245a2dec095d5/.github/workflows/publish.yaml
Publishing logs: github.com/svange/augint-shell/actions/runs/36174146589/attempts/1

Artifact

Subject: augint_shell-0.109.0.tar.gz
SHA-256 checksum: 35eaa0da36304e43a0514becedf5862a3a74f3523df1a2463dd6b30b009ea9e5 Verifying attestations

Release files / augint_shell-0.109.0-py3-none-any.whl

Download URL	augint_shell-0.109.0-py3-none-any.whl
Size	121.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`dcfc095feebbf2549e1a2578c4e44f2948ea71279fc30768d4cab825e9858c08`
BLAKE2b-256 checksum How to use checksums	`d7d1e0209ea14f9dbbe72bd0afd607a5b200788ad055ce122cac07721f7e7f9c`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/svange/augint-shell
Publishing commit: github.com/svange/augint-shell/tree/f2ed6a16b0ba7c5017581b9aa96245a2dec095d5

Workflow

Publishing configuration: github.com/svange/augint-shell/blob/f2ed6a16b0ba7c5017581b9aa96245a2dec095d5/.github/workflows/publish.yaml
Publishing logs: github.com/svange/augint-shell/actions/runs/36174146589/attempts/1

Artifact

Subject: augint_shell-0.109.0-py3-none-any.whl
SHA-256 checksum: dcfc095feebbf2549e1a2578c4e44f2948ea71279fc30768d4cab825e9858c08 Verifying attestations