Metadata-Version: 2.4
Name: taui
Version: 0.9
Summary: Agentic coding interface you can reshape
Project-URL: Homepage, https://github.com/nottherealsanta/taui
Project-URL: Repository, https://github.com/nottherealsanta/taui
Project-URL: Issues, https://github.com/nottherealsanta/taui/issues
Author-email: Santosh <santosh.rajan.work@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,coding,llm,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.13
Requires-Dist: aiosqlite>=0.20
Requires-Dist: httpx>=0.28
Requires-Dist: rich>=13.0
Requires-Dist: textual-diff-view>=0.1.2
Requires-Dist: textual>=3.0
Description-Content-Type: text/markdown

# taui

Taui is a customizable agentic coding interface for developers. It runs as a
full-screen Textual TUI; the terminal app is the product.

Alpha software: APIs, commands, and behavior may change.

## Install

```bash
uvx taui
```

For local development:

```bash
uv run taui
uv run taui --version
uv run taui --login
uv run taui -p copilot -m <model>
uv run taui -p codex -m <model>
uv run taui -d /path/to/project
uv run taui --session <session_id>
```

CLI parsing and app launch live in `taui/main.py:29` and `taui/main.py:90`.

## What It Does

- Runs an async agent loop over provider responses, tool calls, and observations:
  `taui/agent/loop.py:93`.
- Wires providers, tools, extensions, prompts, store, and loop in one composition root:
  `taui/session.py:139`.
- Stores sessions as append-only SQLite event streams in the working directory:
  `taui/store/store.py:97` and `taui/store/stream.py:22`.
- Renders chat, streaming output, approvals, questions, the file sidebar, and session
  modal controls in
  Textual: `taui/tui/app.py:206`.

## Providers

Built-in providers:

| Provider | Auth | Implementation |
| --- | --- | --- |
| GitHub Copilot | device flow | `taui/llm_provider/providers/copilot.py:33` |
| OpenAI Codex | PKCE browser flow | `taui/llm_provider/providers/codex.py:26` |

Run `taui --login` to authenticate. Credentials are loaded through
`taui/llm_provider/config.py:15` and selected by `Config.load()` at
`taui/config.py:64`.

## Commands

Important slash commands are registered in `taui/commands/builtins.py:858`.

| Command | Purpose |
| --- | --- |
| `/help`, `/h`, `/?` | Show help |
| `/model` | Show, refresh, or switch models |
| `/provider` | Show or switch provider |
| `/agents` | List or activate agent profiles |
| `/skills [name\|add <source>]` | List/toggle skills, or install from a source |
| `/sessions` | Open the session picker modal or resume a session |
| `/new [message]` | Start a new session |
| `/compact`, `/context` | Manage or inspect context |
| `/extensions`, `/reload`, `/ext-mode` | Inspect and reload extensions |
| `/i [message]` | Enter self-edit mode |
| `/copy`, `/export` | Copy context or export a session |
| `/hotkeys`, `/keys` | Show key bindings |
| `/verbose`, `/quiet` | Toggle tool output verbosity |
| `/update-providers-models` | Refresh the models.dev cache |

## Keys

App-level bindings are defined in `TauiApp.BINDINGS` at `taui/tui/app.py:399`.
Input-specific bindings are in `ChatInput.BINDINGS` at
`taui/tui/widgets/chat_input.py:64`.

| Key | Action |
| --- | --- |
| `Ctrl+Q` | Quit |
| `Ctrl+N` | New session |
| `Ctrl+C` | Cancel active request or approval |
| `Ctrl+D` | Quit after double press |
| `Ctrl+B` | Toggle file sidebar |
| `Ctrl+R` | Toggle info sidebar |
| `Ctrl+E` | Enter self-edit mode |
| `Ctrl+X` | Context breakdown |
| `Alt+Left/Right` | Focus left/right pane |
| `Ctrl+PageDown/Up` | Next/previous tab |
| `Escape` | Leave mode or dismiss panels |

## Configuration

Config fields are defined in `taui/config.py:33`.

```toml
[taui]
provider = "copilot"
model = "claude-sonnet-4.5"
max_turns = 50
verbose_tools = true

[taui.tool_policy]
bash = "confirm"
write = "confirm"
edit = "confirm"

[taui.permission]
read = { "*" = "allow" }
bash = { "git status" = "allow", "*" = "ask" }
```

Tool policy evaluation is in `taui/tools/executor.py:42`; pattern permissions are in
`taui/permissions.py:38`.

## Extensions And Skills

Extensions are Python files loaded from `~/.taui/extensions/*.py` and
`.taui/extensions/*.py`. The `register(ctx)` context is defined at
`taui/extensions/__init__.py:66`; extension loading starts at
`taui/extensions/__init__.py:169`.

Skills are `SKILL.md` files discovered by `taui/skills/__init__.py:91` and loaded lazily
by `taui/skills/__init__.py:52`.

Install skills from external sources (compatible with
[`vercel-labs/skills`](https://github.com/vercel-labs/skills)) with
`/skills add <source>`, or just paste `npx skills add <source>` / a bare repo
ref into the chat input. Sources may be GitHub shorthand (`owner/repo`), a full
git/GitHub/GitLab URL, a URL pointing at one skill
(`…/tree/<ref>/<path>`), an SSH git URL, or a local path; add `-g` to install
globally. The installer lives in `taui/skills/installer.py`, and the self-edit
agent exposes the same engine as the `install_skill` tool.

## Documentation

- Product and architecture overview: `docs/taui.md:1`
- Runtime flow: `docs/runtime.md:1`
- Tools and permissions: `docs/tools.md:1`, `docs/permission-dsl.md:1`
- Extensions, hooks, skills, and agents: `docs/build-your-harness.md:1`,
  `docs/extension-hooks.md:1`, `docs/agents.md:1`
- Providers and auth: `docs/providers.md:1`
- Context and prompts: `docs/context-strategies.md:1`, `docs/system-prompt.md:1`
- Tests and visual harness: `docs/testing.md:1`

## Checks

```bash
uv run ruff check .
uv run python -m pytest -q -m tools  # replace tools with the changed domain
```

Use domain groups for focused checks instead of running everything:

```bash
uv run python -m pytest -q -m tools
uv run python -m pytest -q -m agent
uv run python -m pytest -q -m "agent or provider"
uv run python -m pytest -q -m tui
```

Target focused tests first when changing one subsystem. The scenario and visual harness
are documented in `docs/testing.md:1`.
