claux 20260422.0.0

Terminal AI coding assistant with tool execution
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

# claux

A terminal-based AI coding assistant written in Rust. Streams responses, executes tools, manages sessions, and stays out of your way.

## Features

- **Streaming chat** with tool execution (Read, Write, Edit, Glob, Grep, Bash, WebFetch, Agent)
- **Interactive permissions** — prompts before writes, `y/n/a` (always allow per-session)
- **Session persistence** — JSONL-based, resume with `/resume` or `--resume`
- **Compaction** — `/compact` summarizes conversation to free context
- **Model switching** — `/model <name>` mid-conversation
- **Sub-agents** — Agent tool spawns scoped sub-conversations
- **Auto-compact** — triggers when conversation gets large
- **Cost tracking** — per-model token usage and USD estimates
- **Context assembly** — git status, CLAUDE.md, environment info in system prompt
- **TUI mode** — full-screen ratatui interface with `--tui`
- **Multi-provider** — Anthropic, OpenAI, Ollama, or any OpenAI-compatible endpoint
- **OAuth support** — works with existing `claude login` credentials
- **Markdown rendering** — code blocks, bold, headers in the TUI

## Screenshots

The TUI in action. These are generated by [tuishot](https://github.com/ducks/tuishot)
from claux's own code — `cargo test` fails if they drift, so they can't go
stale.

![Session browser with two projects](docs/screens/home-populated.svg)

![Creating a new session](docs/screens/home-new-session.svg)

## Install

```bash
# From crates.io
cargo install claux

# From source
cargo install --path .
```

Requires Rust 1.88+. A `shell.nix` is included.

## Auth

claux resolves authentication in order:

1. `api_key` in `~/.config/claux/config.toml`
2. `api_key_cmd` (shell command that returns a key)
3. `ANTHROPIC_API_KEY` environment variable
4. OAuth token from `~/.claude/.credentials.json`

If you've already run `claude login`, claux picks up those credentials automatically.

### OpenAI-compatible providers

For Ollama, vLLM, LMStudio, OpenAI, or any hosted endpoint:

```toml
model = "llama3"
openai_base_url = "http://localhost:11434/v1"
openai_provider_name = "ollama"
```

API keys via command (works with 1Password, Vault, etc.):

```toml
model = "gpt-4o"
openai_base_url = "https://api.openai.com/v1"
openai_api_key_cmd = "op read 'op://vault/OpenAI/key'"
openai_provider_name = "openai"
```

## Usage

```bash
# Interactive REPL (default)
claux

# Full-screen TUI
claux --tui

# One-shot
claux -p "explain this error"

# Resume a session
claux --resume 20260401-143022
```

## Commands

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/cost` | Token usage and estimated cost |
| `/compact` | Summarize conversation to free context |
| `/model [name]` | Show or switch model |
| `/resume [id]` | List or resume past sessions |
| `/clear` | Clear screen |
| `/exit` | Exit |

## Config

Global: `~/.config/claux/config.toml`

```toml
model = "claude-sonnet-4-20250514"
permission_mode = "default"  # default | accept-edits | bypass | plan
```

Per-project: `.claux.toml` in the project root (overrides global).

## Permission Modes

| Mode | Reads | File edits | Bash |
|------|-------|------------|------|
| `default` | auto | prompt | prompt |
| `accept-edits` | auto | auto | prompt |
| `bypass` | auto | auto | auto |
| `plan` | auto | denied | denied |

## License

MIT