# agentu

agentu is a small local agent written in Go. The current MVP is a terminal chat
UI with OpenAI-compatible providers, streaming responses, session-level
model/provider switching, and local tools.

## Current MVP

- TUI-first chat experience with a light theme by default.
- OpenAI-compatible `/v1/chat/completions` provider support.
- Multiple providers from `~/.agentu/config.yaml`.
- Session-only provider, model, and thinking-level switching.
- Read-only project tools enabled by default.
- Built-in web search and URL fetching.
- `--yolo` mode for file writes and shell execution.

## Quick Start

```sh
mkdir -p ~/.agentu
cp agentu.example.yaml ~/.agentu/config.yaml
export AGENTU_API_KEY='your-api-key'
go run .
```

Use `--yolo` only when you want agentu to write files or run shell commands:

```sh
go run . --yolo
```

## Config

By default, agentu reads:

```text
~/.agentu/config.yaml
```

Use `--config <path>` to load another file.

```yaml
providers:
  loveuer:
    base_url: https://ai.loveuer.com
    api_key: ${AGENTU_API_KEY}
    models:
      - id: deepseek-v4-flash
        thinking: none
        context: 256000
```

Web tools are enabled by default with a built-in no-key backend. agentu exposes
`web_search` for current or external web information and `web_fetch` for reading
a known URL.

Provider names are the keys under `providers`. At startup, agentu selects the
first provider by name. Use `/model provider <name>` to switch providers for the
current session.

`models` is required. `/model model <name>` is restricted to that list. Each
entry is an object with:

- `id`: model name sent to the provider.
- `thinking`: optional default thinking level for that model.
- `context`: optional context-window token count used for auto-compaction.

If `model` is omitted, agentu uses the first `models` entry. The `agent` block
is optional: `working_dir`, `tool_timeout`, `system_prompt`, and
`max_context_tokens` all have defaults. `max_context_tokens` overrides the
selected model's `context` when set.

Supported thinking values are:

```text
none, middle, high, xhigh, max
```

When configured or changed with `/model thinking ...`, the value is sent as a
top-level OpenAI-compatible request field named `thinking`.

## CLI Flags

```sh
go run . [flags]
```

- `--config <path>` loads a YAML config file. Default: `~/.agentu/config.yaml`.
- `--theme light|dark` selects the TUI theme. Default: `light`.
- `--plain` uses the simple line-based REPL instead of the TUI.
- `--yolo` enables automatic file writes and shell execution.
- `--resume <id>` resumes a saved session from `~/.agentu/sessions`.

## TUI Controls

- `enter` sends the message.
- `ctrl+j` or `alt+enter` inserts a newline.
- The input starts at one line and grows up to six lines.
- `page up` / `page down` scrolls the transcript.
- `esc` cancels a running response.
- Type `/` to show available commands.

Slash commands:

- `/clear` resets conversation history.
- `/compact` summarizes older conversation history and keeps recent context.
- `/status` shows changed files with `git status --short`.
- `/diff [--stat] [path...]` shows the unstaged git diff.
- `/test [command...]` runs a project test command; defaults to `go test ./...` for Go modules or `npm test` for Node projects.
- `/model` shows current provider, model, thinking, and switch usage.
- `/model provider <name>` switches provider for the current session.
- `/model model <name>` or `/model <name>` switches model for the current session.
- `/model thinking <none|middle|high|xhigh|max>` changes thinking for the current session.
- `/sessions` lists saved sessions.
- `/resume [id]` resumes by ID or opens an interactive picker.
- `/rename <name>` renames the current session.
- `/new` saves the current session and starts a fresh one.
- `/exit` or `/quit` exits.

## Local Tools

Read-only tools are available by default:

- `file_read`
- `file_list`
- `file_search` with optional `context_lines` and `max_results`
- `code_symbols` for Go packages, imports, types, functions, and methods

Web tools are also available in read-only mode:

- `web_search`
- `web_fetch`

`--yolo` additionally enables:

- `file_write`
- `shell_run`

Use `--yolo` for prompts that ask agentu to run or inspect local commands, for
example:

```text
请帮我运行 `go test ./...` 并总结结果
```

## Development

Run the verification suite:

```sh
go test ./...
go vet ./...
go build .
```

Local config and build outputs are intentionally ignored by git.

## Notes

- Provider/model/thinking changes are session-only; agentu does not write them
  back to `~/.agentu/config.yaml`.
- The config schema is intentionally strict during MVP development. Deprecated
  fields such as `provider` or `active_provider` are rejected.