# LLMTune CLI

AI coding agent for your terminal, powered by [api.llmtune.io](https://api.llmtune.io).

## Quick Start

```bash
# Install globally
npm install -g llmtune

# Or run directly
npx llmtune

# Configure your API key
llmtune login

# Start coding
cd my-project
llmtune chat
```

## Commands

| Command | Description |
|---------|-------------|
| `llmtune login` | Configure API key and settings |
| `llmtune chat` | Start interactive coding session |
| `llmtune models` | List available models |
| `llmtune config` | Show current configuration |
| `llmtune skills list` | List installed and marketplace skills |
| `llmtune skills install <name>` | Install a skill from marketplace |
| `llmtune skills publish` | Publish current directory as a skill |
| `llmtune skills sign <name>` | Cryptographically sign a skill |

## Chat Commands

Inside the REPL, use these slash commands:

| Command | Description |
|---------|-------------|
| `/help` | Show available commands |
| `/exit` | Exit the REPL |
| `/clear` | Clear conversation history |
| `/context` | Show token usage breakdown by category |
| `/compact` | Summarize old messages to free tokens |
| `/uncompact` | Restore original conversation from history |
| `/model <name>` | Switch to a different model |
| `/stream` | Toggle streaming mode |
| `/verbose` | Toggle verbose tool output |
| `/trust <tool>` | Skip confirmation for a tool |
| `/skills` | List loaded skills |
| `/<skill> [args]` | Execute a skill |
| `/memory` | Show cross-session memory |
| `/memory clear` | Clear all memory |
| `/save` | Save session to file |
| `/install <skill>` | Install a skill from marketplace |
| `/sandbox` | Toggle Docker sandbox mode |

## Skills

Skills are reusable workflows defined in `SKILL.md` files. They live in:

- `~/.llmtune/skills/<skill-name>/SKILL.md` — user skills
- `.llmtune/skills/<skill-name>/SKILL.md` — project skills

### Creating a Skill

Create a directory with a `SKILL.md` file:

```
my-skill/
  SKILL.md
```

Example `SKILL.md`:

```markdown
---
description: "Explain code with clear diagrams"
user-invocable: true
allowed-tools: [read, glob, grep]
arguments: [file_path]
trust: local
---

Analyze the code in {{file_path}} and explain it with:
1. A high-level overview
2. Key functions and their purposes
3. Data flow diagram (in mermaid syntax)
4. Potential improvements
```

### Trust Levels

| Level | Tools Allowed | Description |
|-------|---------------|-------------|
| `local` | All | Created by user, full trust |
| `community` | read, glob, grep | Installed from marketplace, sandboxed |
| `verified` | All | Reviewed by LLMTune team |
| `signed` | All | Cryptographically signed by author |

## Context System

The CLI automatically builds context from your workspace:

- **Git context** — current branch, recent commits, modified files
- **Workspace snapshot** — file types, key files, directory structure
- **Project instructions** — loaded from `LLMTUNE.md` or `CLAUDE.md`
- **Memory** — cross-session preferences and decisions stored in `~/.llmtune/memory/`

Context is cached by git SHA — repeated requests are served from cache until you make a new commit.

## Smart Compaction

When conversations get long, `/compact` summarizes older messages using an LLM, preserving:
- User intent and requests
- Key technical decisions
- Files examined or modified
- Errors and resolutions

The original conversation is always preserved. Use `/uncompact` to restore it.

## Docker Sandbox (Enterprise)

For enterprise environments, the CLI can run tools inside a Docker container:

```bash
llmtune chat --sandbox
```

Or toggle at runtime with `/sandbox`. This isolates bash, write, and edit operations inside a container.

## Memory

The CLI stores cross-session knowledge in `~/.llmtune/memory/`:

- `preferences.md` — coding style, language preferences
- `project-notes.md` — architecture decisions
- `decisions.md` — key decisions made during sessions
- `architecture.md` — project structure notes

The agent reads these automatically and can write to them.

## Telemetry

Session telemetry is stored locally in `~/.llmtune/logs/{session-id}.jsonl`:

- Tool calls with latency
- LLM token usage and cost estimates
- Compaction events
- Errors with context

No data is sent externally unless you opt in.

## Configuration

Configuration is stored in `~/.llmtune/config.json`:

```json
{
  "apiKey": "sk_...",
  "apiBase": "https://api.llmtune.io/api/agent/v1",
  "defaultModel": "z-ai/GLM-5.1"
}
```

## Directory Structure

```
~/.llmtune/
  config.json           # API key and settings
  skills/               # Installed skills
  memory/               # Cross-session memory
  sessions/             # Saved conversation history
  logs/                 # Telemetry JSONL files
  cache/                # Context cache (SHA-keyed)
```

## License

MIT