# Desire Paths in VT Code

This document explains the design philosophy of paving "desire paths" in VT Code—optimizing the tool to work naturally with how agents think and work.

## Philosophy

A desire path is a common pattern that emerges from how users actually behave, rather than how designers intended them to behave. In software, this principle means:

**When an agent intuitively guesses wrong about a feature, we should improve the interface to make that guess right.**

Instead of:

- Documenting that agents are using the tool incorrectly
- Rejecting intuitive commands

We do:

- Add aliases that match intuitive expectations
- Implement flags agents naturally expect
- Design interfaces that align with agent mental models

Over time, this compounds. Each small UX improvement reduces friction, and agents naturally stop making "mistakes" because the tool now works the way they naturally think.

## Current Paved Paths

### Cargo Aliases

Agents intuitively try short command names. We've paved these paths:

| Intuitive Guess | Mapped Command | Status        |
| --------------- | -------------- | ------------- |
| `cargo t`       | `cargo test`   | v Implemented |
| `cargo c`       | `cargo check`  | v Implemented |
| `cargo r`       | `cargo run`    | v Implemented |

**Location**: `.cargo/config.toml` → `[alias]` section

**Why it works**: Agents coming from other CLI tools expect abbreviated commands. By providing these aliases, we eliminate the cognitive overhead of remembering full command names.

### Test Invocation Patterns

Agents expect these patterns to work without explanation:

| Intuitive Usage            | Behavior                         | Status           |
| -------------------------- | -------------------------------- | ---------------- |
| `cargo test function_name` | Run tests matching function name | v Works natively |
| `cargo test --lib`         | Run unit tests only              | v Works natively |
| `cargo test --integration` | Run integration tests only       | v Works natively |

These are native Cargo behaviors, but documented here for agent awareness.

## Desire Paths to Implement

These are patterns agents have tried or might try that aren't yet smooth:

### 1. Tool Operation Shortcuts

**Current friction**:

```
unified_search {
  "action": "grep",
  "pattern": "fn main",
  "path": "src/"
}
```

**Intuitive expectation**:

```
unified_search grep "fn main" src/
```

**Priority**: Medium (requires tool refactoring)

### 2. Configuration Shortcuts

**Current friction**:

- Agents must know exact config file locations
- Need to remember TOML structure

**Intuitive expectation**:

- `vtcode config set llm.model gpt-4`
- `vtcode config get llm.model`
- `vtcode config edit` (opens default editor)

**Priority**: Low (workaround exists: direct file editing)

## How to Report Friction

If you notice an agent (or yourself) repeatedly guessing at:

- A flag that doesn't exist
- A command structure that's not intuitive
- A subcommand name that's confusing
- A configuration pattern that's hard to remember

1. **Document it** in this file under "Desire Paths to Implement"
2. **Note the pattern**: Why did they guess that way?
3. **Propose the improvement**: What would be more intuitive?
4. **Prioritize**: Is it a common blocker or edge case?

## Implementation Checklist

When implementing a new desire path:

- [ ] Identify the intuitive expectation
- [ ] Implement the alias/shortcut/flag
- [ ] Verify it works with `cargo test` or similar
- [ ] Document in AGENTS.md
- [ ] Document in development/DESIRE_PATHS.md
- [ ] Consider if the change needs release notes
- [ ] Update any relevant CLI help text

## Related Documentation

- **AGENTS.md**: Agent UX & Desire Paths section for quick reference
- **CLAUDE.md**: Development guidelines (includes Desire Paths philosophy)
- **docs/ARCHITECTURE.md**: System architecture

## Examples in Practice

### Example: Cargo Aliases Success

**Before**: Agents would type `cargo test` (correct), but try `cargo t` (wrong)

- Error: "Unknown subcommand"
- Friction: Agent has to remember the full command

**After**: Added `t`, `c`, `r` aliases in `.cargo/config.toml`

- Result: Both `cargo test` and `cargo t` work
- Friction: Eliminated
- Bonus: Tool aligns with Unix conventions (short flags)

This small change has compounding effects:

- Agents build muscle memory faster
- Tool feels more polished
- Reduces cognitive load

### Example: Help Text Improvement

When agents ask for help, the response should be clear and actionable:

```bash
$ cargo invalid-command
error: unknown subcommand `invalid-command`

Did you mean one of these?
    test     Run tests (`cargo t` for short)
    build    Build the project
    check    Check compilation (`cargo c` for short)
```

By making suggestions and noting aliases in help text, we guide agents toward good practices.

---

**Last Updated**: Dec 30, 2025
**Philosophy Introduced By**: Amp AI Agent
**Based On**: Wikipedia's "Desire Path" concept
