trace.ai-cli/README.markdown

A powerful AI-powered CLI tool

# Trace.AI CLI

![Trace.AI logo](image.png)

AI powered CLI Platform  
v1.3.0 | Powered by Mixkey

Trace.AI CLI is an interactive terminal app for analyzing files, folders, images, and system state, managing reusable memory, running shell commands, and routing work through connected agents.

## Features

- **Path-first analysis**: Pass a file, folder, or image directly and Trace.AI auto-detects how to analyze it.
- **Plain-language queries**: Ask questions directly when you do not need to target a specific path.
- **Persistent memory**: Save text, files, folders, and websocket sources with `/memory` and reuse them across queries.
- **Interactive pickers**: Use `/` for command suggestions and `@` for context-sensitive pickers.
- **Agent workflow support**: Sign in, connect to an agent endpoint, and select trained agents from the terminal.
- **Shell passthrough**: Run local commands with `!<command>` without leaving the CLI.
- **System inspection**: Query hardware and OS details with `/system [query]`.
- **Mode control**: Switch between Fast, Balanced, and Think with `/mode <1|2|3>`.
- **Modern terminal UI**: Includes branded ASCII startup, themed output, dropdowns, and focused status panels.

## Installation

### Prerequisites

- **Node.js**: Version 14.0.0 or higher.
- **npm**: Included with Node.js.

### Install via npm

```bash
npm install -g trace.ai-cli
```

If you hit permission issues, either use `sudo` or switch npm to a user-owned directory.

Verify the install:

```bash
trace-ai --version
```

## Quick Start

Start the interactive CLI:

```bash
trace-ai
```

The prompt opens as:

```text
Trace.AI > Type your message or /
```

Common first actions:

```text
src/index.js explain the entry flow
docs/ summarize the project structure
diagram.png extract the flow from this image
/memory README.markdown
/memory "This repo uses Supabase auth and websocket agents"
/system how much memory is available?
!npm test
```

## Command Reference

### Primary Input Patterns

- `<path> [question]` Analyze a file, folder, or image using auto-detection.
- `!<command>` Run a shell command such as `!ls` or `!npm start`.
- `@` Context-sensitive picker:
  - Picks files from active memory folders when no agent is connected.
  - Picks trained agents when an agent connection is active.

### Memory

- `/memory` Show memory entries and memory commands.
- `/memory "text"` Add plain text as memory.
- `/memory <path>` Add a file, folder, or websocket source such as `wss://...` as memory.
- `/memory show` Show all memories.
- `/memory 1,2,3` Activate specific memories.
- `/memory 0` Deselect all active memories.

### Agent and Auth

- `/auth` Show account information or start sign-in.
- `/auth out` Sign out.
- `/agent <url>` Connect to an agent endpoint.
- `@agent-name <task>` Select a trained agent and send it a task when connected.

### General

- `/clear` Clear the screen.
- `/clear m` Clear all memories.
- `/clear m1,2` Clear specific memory entries.
- `/help` Show all commands.
- `/stats` Show session statistics.
- `/system [query]` Query system information.
- `/mode <1|2|3>` Set the AI mode: `1=Fast`, `2=Balanced`, `3=Think`.
- `/exit` Disconnect the agent or close the CLI.

## Examples

### Analyze a file

```text
src/app.js explain the main control flow
```

### Analyze a folder

```text
src/ what architecture pattern is this project using?
```

### Analyze an image

```text
diagram.png describe the sequence shown here
```

### Work with memory

```text
/memory README.markdown
/memory ./src
/memory "The backend uses Supabase for auth"
/memory show
/memory 1,3
```

### Use shell commands

```text
!git status
!npm run start
```

### Connect to an agent

```text
/auth
/agent wss://your-agent-endpoint
@release manager draft release notes from the latest changes
```

## Notes

- Memory is persisted under your home directory in the Trace.AI config folder.
- When a websocket memory source is active, plain text queries can be routed through that source.
- The `@` picker changes behavior based on whether you are connected to an agent.

## License

MIT