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

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.

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

augint_shell-0.108.0.tar.gz (102.6 kB view details)

Uploaded Sep 3, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

augint_shell-0.108.0-py3-none-any.whl (119.0 kB view details)

Uploaded Sep 3, 2026 Python 3

File details

Details for the file augint_shell-0.108.0.tar.gz.

File metadata

Download URL: augint_shell-0.108.0.tar.gz
Upload date: Sep 3, 2026
Size: 102.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for augint_shell-0.108.0.tar.gz
Algorithm	Hash digest
SHA256	`4c7afca3ebcaaedd2c855d5d54a5fa3178a25d4100c553ad2827811d4ca21c5e`
MD5	`a8112ac616401e713d129cb7a56222ca`
BLAKE2b-256	`b47e1ca2286c0b8c698e5c8b8feb319f5a86d75700b2b23604305caf5eab10f2`

See more details on using hashes here.

Provenance

The following attestation bundles were made for augint_shell-0.108.0.tar.gz:

Publisher: publish.yaml on svange/augint-shell

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: augint_shell-0.108.0.tar.gz
- Subject digest: 4c7afca3ebcaaedd2c855d5d54a5fa3178a25d4100c553ad2827811d4ca21c5e
- Sigstore transparency entry: 2693128817
- Sigstore integration time: Sep 3, 2026
Source repository:
- Permalink: svange/augint-shell@0b67657d07f2a43594e1716f22e1194ce079229d
- Branch / Tag: refs/heads/main
- Owner: https://github.com/svange
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yaml@0b67657d07f2a43594e1716f22e1194ce079229d
- Trigger Event: push