Metadata-Version: 2.3
Name: augint-shell
Version: 0.84.4
Summary: Launch AI coding tools and local LLMs in Docker containers
Author: svange
Requires-Dist: docker>=7.0.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=14.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# augint-shell CLI

[![PyPI version](https://badge.fury.io/py/augint-shell.svg)](https://badge.fury.io/py/augint-shell)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Tests](https://github.com/svange/augint-shell/actions/workflows/pipeline.yaml/badge.svg)](https://github.com/svange/augint-shell/actions)
[![License](https://img.shields.io/badge/license-proprietary-red.svg)](LICENSE)

Launch AI coding tools and local LLMs in Docker containers.

## Documentation & Reports

| Resource | Description |
|----------|-------------|
| [API Documentation](https://svange.github.io/augint-shell/ai_shell.html) | pdoc-generated API reference |
| [Test Coverage](https://svange.github.io/augint-shell/coverage/htmlcov/) | HTML coverage report |
| [Test Results](https://svange.github.io/augint-shell/tests/test-report.html) | Unit test results |
| [Security Scans](https://svange.github.io/augint-shell/security/security-reports.html) | Bandit, pip-audit results |
| [License Compliance](https://svange.github.io/augint-shell/compliance/license-report.html) | Dependency license report |
| [PyPI Package](https://pypi.org/project/augint-shell/) | Published package |

## Installation

```bash
pip install augint-shell
```

Or as a dev dependency:

```bash
uv add --dev augint-shell
```

## Quick Start

```bash
# 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):

```yaml
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](https://github.com/ollama/ollama/issues/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`](https://github.com/ChromeDevTools/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

```bash
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:

```toml
[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
