augint-shell 0.81.0

Launch AI coding tools and local LLMs in Docker containers

augint-shell CLI

Launch AI coding tools and local LLMs in Docker containers.

Documentation & Reports

Resource	Description
API Documentation	pdoc-generated API reference
Test Coverage	HTML coverage report
Test Results	Unit test results
Security Scans	Bandit, pip-audit results
License Compliance	Dependency license report
PyPI Package	Published package

Installation

pip install augint-shell

Or as a dev dependency:

uv add --dev augint-shell

Quick Start

# 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

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
ai-shell aider	Launch aider with local LLM
ai-shell shell	Bash shell in dev container

LLM Stack

Command	Description
ai-shell llm up	Start Ollama (add --webui, --whisper, --voice-agent, --n8n, or --all for optional stacks)
ai-shell llm down	Stop LLM stack
ai-shell llm pull	Pull configured models
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

Configuration

Optional .ai-shell.yaml in your project root (YAML is the default; TOML is also accepted — see ai-shell init for the full generated template with per-section rationale):

container:
  image: svange/augint-shell
  image_tag: latest
  extra_env:
    MY_VAR: value

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
  extra_models: []   # additional Ollama tags to pull alongside the 4 slots

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

The previous primary_model / fallback_model keys were removed. They were role-ambiguous (chat vs. coding). If you had them set, move them to the matching slot above. ai-shell will refuse to start with those legacy keys present and print a migration hint.

ai-shell does not manage tool-specific config files for Codex, OpenCode, or Aider. Use augint-opencodex or the tools' native config files for those, and use ai-shell for container/runtime settings such as AWS profiles, local LLM ports, and Claude options.

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 (abliterated Qwen3-Coder)	OpenCode (selectable)

Each pair shares a base model — primary is the standard aligned release; secondary is the huihui.ai abliterated variant (refusal directions neutralized via weight surgery, benchmark quality preserved). Switching primary <-> secondary within a slot keeps tool formats and context semantics identical.

ai-shell llm pull / ai-shell llm setup downloads all 4 slots plus any extra_models entries, deduped.

Three caveats worth knowing:

1. Qwen3.5 Ollama tool calling is broken (ollama #14493, open). This does not affect Open WebUI's default chat with web search and RAG — those run server-side in WebUI without touching Ollama's tools API. It does affect agent CLIs routed through Ollama's /v1/chat/completions tools array, which is why the chat slots are Qwen3.5 and the coding slots are Qwen3-Coder (explicit tools badge, working parser).
2. Ollama num_ctx defaults to 4096 for every model, well below what modern agent prompts need (Claude Code sends ~35K tokens). context_size in your config is applied via Modelfile override during llm setup — leave it at 32768 unless you have a reason.
3. Qwen3-Coder tool-count cliff: reliable native tool_calls emission below ~5 registered tools; above that the model may emit XML inside content and some parsers miss it. Keep agent tool sets tight.

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 the "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. Default model: Systran/faster-distil-whisper-large-v3 (preloaded). GPU image used automatically when NVIDIA is detected; container auto-recreates if GPU availability changes.
--voice-agent	Pipecat voice agent	8010	Experimental. Built locally on first use from docker/voice-agent/. Push-to-talk PWA over WebSocket (Speaches STT -> Ollama -> Kokoro TTS). See VOICE_AGENT_PLAN.md.
--n8n	n8n	5678	Workflow automation, standalone.

How It Works

• Pulls a pre-built Docker image from Docker Hub (svange/augint-shell)
• Creates per-project containers named augint-shell-{project}-dev
• Mounts your project directory, SSH keys, AWS credentials, and tool configs
• Runs AI tools interactively inside the container
• Supports concurrent instances across multiple projects
• GPU-capable containers (Ollama, Kokoro, Whisper) auto-detect NVIDIA GPUs and recreate themselves if GPU availability changes

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

The dev container cannot open a browser on the Windows host, which blocks OAuth popups, CAPTCHA pages, and any "click around in a logged-in site" task. ai-shell claude --local-chrome bridges Claude inside the container to your real Chrome on Windows through the Chrome DevTools Protocol, using the official chrome-devtools-mcp server.

What you get:

• Claude drives Chrome tabs on your Windows desktop, visible in real time.
• Uses a separate Chrome profile per project -- your normal browsing is untouched, and each repo keeps its own logged-in state.
• No Chrome extension. No third-party service. All traffic stays on localhost between the container and the host.

How it works

ai-shell claude --local-chrome

ai-shell automatically:

1. Computes a stable debug port and Chrome profile for the current project.
2. Reuses that project's Chrome if it is already running.
3. If not, launches Chrome for the project on its assigned port with its own profile under %LOCALAPPDATA%\Google\Chrome\ai-shell\....
4. Starts a TCP proxy inside the container and injects chrome-devtools-mcp as an MCP server for Claude.

No manual setup required. Chrome stays open after Claude exits so your login sessions persist. Sign in to whatever accounts you need in that Chrome window (first time only; cookies persist in the profile).

Persisting the flag

Add to ai-shell.toml (or the YAML equivalent) if you always want this on for a project:

[claude]
local_chrome = true

Or set the environment variable: AI_SHELL_LOCAL_CHROME=1.

Manual Chrome launch (fallback)

If ai-shell can't find chrome.exe automatically, launch Chrome yourself using the project-specific port and profile path that ai-shell prints in the error message. The shape of the command is:

chrome.exe --remote-debugging-port=<project-port> --remote-debugging-address=127.0.0.1 --remote-allow-origins=* --user-data-dir="%LOCALAPPDATA%\Google\Chrome\ai-shell\<project-slug>"

Troubleshooting

• "Chrome could not be found or launched" -- Chrome is not installed at a standard location. Use the manual launch command above, or set the path in your system PATH.
• Tabs appear empty / not logged in -- Sign in to the accounts you need inside the auto-launched Chrome for that project. Cookies persist in that project's profile across sessions.
• A different repo opened the wrong Chrome window -- Each project now gets its own Chrome profile and debug port. Re-run from the correct repo so ai-shell attaches to that repo's browser instance.
• Firefox / Safari -- not supported. chrome-devtools-mcp requires a Chromium-based browser. Edge works with the same flags but has not been tested here.

Standardization architecture

augint-shell also ships the skill bundle and Python machinery for repository standardization. The system distributes work across three repositories:

• augint-shell — content owner: canonical vocabulary, templates, generators, and the orchestration skills.
• augint-github (ai-gh) — thin GitHub-state mutation API: rulesets apply, config standardize, OIDC trust.
• augint-tools (ai-tools) — multi-repo workflow helpers and workspace enumeration via workspace.yaml.

Each repo releases independently. Changing a gate name is a one-repo change in augint-shell — downstream tools read the canon at runtime.

Ownership matrix

Concern	Owner	Surface
Gate canon (gates.json)	augint-shell	templates/claude/skills/ai-standardize-repo/gates.json
Ruleset spec generation	augint-shell	ai_shell.standardize.rulesets
Ruleset application to GitHub	augint-github	ai-gh rulesets apply <spec>
Workflow job snippets + minimum specs	augint-shell	templates/.../ai-standardize-pipeline/jobs/
Workflow file generation	augint-shell (AI-mediated prose)	/ai-standardize-pipeline skill
Renovate config	augint-shell	ai-shell standardize renovate
Pre-commit config	augint-shell	ai-shell standardize precommit
Semantic-release config	augint-shell	ai-shell standardize release (tomlkit merge for python)
Dotfiles (.editorconfig, .gitignore)	augint-shell	ai-shell standardize dotfiles
Repo merge settings	augint-github	ai-gh config --standardize
OIDC trust	augint-shell + augint-github	/ai-setup-oidc skill orchestrates
Secrets / variables	augint-github	chezmoi + ai-gh sync
Workspace enumeration	augint-tools	workspace.yaml + ai-tools workspace inspect/graph/foreach/...
Repo / workspace workflow helpers	augint-tools	ai-tools repo, ai-tools workspace
Standardization orchestration (single-repo)	augint-shell	/ai-standardize-repo
Standardization orchestration (workspace)	augint-shell	/ai-workspace-standardize
Workspace bulk verify	augint-shell skill layer	/ai-workspace-standardize --verify loops over children calling ai-tools standardize <child-path> --verify --json
AI agent configuration	augint-shell (.ai-shell.toml)	container/runtime settings only — NOT tool-specific Codex/OpenCode/Aider config

Canonical gate vocabulary

Every repo enforces the same 5 pre-merge gates as required status checks via branch rulesets. iac repos additionally enforce 1 post-deploy gate on the production branch. Source of truth: templates/claude/skills/ai-standardize-repo/gates.json. Skills that name a gate read it from there; they never hardcode.

Gate	Scope	What it checks
Code quality	all repos	linting, formatting, type checking, file hygiene
Security	all repos	Bandit/Semgrep SAST, dependency vulnerabilities
Unit tests	all repos	tests + coverage floor (>=80%)
Compliance	all repos	GPL/AGPL/LGPL license rejection
Build validation	all repos	uv build / sam build / cdk synth / npm run build / terraform validate
Acceptance tests	iac production only	runs on dev's tip after deploy; required context on iac_production ruleset; satisfied on the promotion PR

Repo type and language detection

Detection is code-based via ai-shell standardize detect --json. There is no .ai-shell.toml dependency for repo-shape decisions.

Language:

• Python — pyproject.toml with [project].name AND no [tool.uv].package = false
• Node — package.json AND (no pyproject.toml OR pyproject.toml has [tool.uv].package = false)
• The package = false marker is authoritative — it says "this pyproject is a dependency container, not a buildable Python package"

Repo type:

• iac if ANY of: samconfig.toml, cdk.json, *.tf at root, serverless.yml, OR a workflow file contains sam deploy, cdk deploy, terraform apply, aws s3 sync, or aws-actions/configure-aws-credentials
• library if a workflow file publishes via pypa/gh-action-pypi-publish, twine upload, uv publish, or npm publish
• Publish wins over deploy when both signals are present — a library with SAM-based test infrastructure (e.g. ai-lls-lib) is still a library

Pipeline architecture principles

• Single pipeline.yaml per repo. All canonical gates inline as jobs in one workflow. No reusable workflow split (_gate-*.yaml). This preserves the unified GitHub Actions DAG view per CI run.
• AI-mediated merge, not Python. The Python layer is read-only: validate(path) returns a DriftReport; canonical_jobs(language, repo_type) returns inline job snippets the AI uses as reference. The /ai-standardize-pipeline skill drives Claude through the merge, handling legacy renames (Pre-commit checks -> Code quality, Integration tests/Smoke tests/E2E * -> Acceptance tests), missing gate insertion, custom job preservation, and special patterns like parallelized post-deploy tests (synthetic Acceptance tests aggregator that needs: [<parallel test jobs>]).
• Minimum-spec validation. Each canonical gate declares required steps in order. Users may add custom steps anywhere as long as required ones appear in the declared order. Action SHAs and step name: fields are ignored; only uses: (action path substring) and run: (regex, MULTILINE+DOTALL for multi-line shell continuations) count.
• One-shot, no two-phase migration. Standardization is a single invocation per repo. No "run once to scaffold, edit by hand, run again to verify."

Execution scopes

Command	Scope
/ai-standardize-pipeline [<path>]	Single section: pipeline.yaml merge (AI-mediated)
/ai-standardize-precommit [<path>]	Single section: pre-commit config
/ai-standardize-renovate [<path>]	Single section: Renovate config
/ai-standardize-release [<path>]	Single section: semantic-release config
/ai-standardize-dotfiles [<path>]	Single section: .editorconfig, .gitignore
/ai-standardize-repo --all [<path>]	Full single-repo 10-step sequence
/ai-standardize-repo --verify [<path>]	Read-only drift report for a single repo
/ai-workspace-standardize [--verify] [--only ...]	Workspace-level orchestration over every child repo in dep order

Requirements

• Docker
• Python >= 3.12