aimagicx-cli

v0.1.9

Published

4 days ago

AI Magicx CLI coding agent - AI-powered coding assistant

0High
0Medium
0Low

aimagicx

ai cli coding-assistant aimagicx llm developer-tools agent

AI Magicx CLI

An AI-powered coding agent for the terminal. AI Magicx brings intelligent code assistance directly to your command line with support for multiple LLM providers, persistent sessions, semantic code search, and extensible tools.

Features

Multi-Provider Support - Use OpenAI, Anthropic, GitHub Copilot, OpenRouter, Groq, and more
Interactive TUI - Rich terminal interface with markdown rendering and alternate screen buffer
Agent Mode - AI with access to file operations, shell commands, and web search
Approval Modes - Control agent autonomy: read-only, auto (default), or full
Background Tasks (Subagents) - Spawn parallel agents for concurrent work
Session Management - Resume conversations, auto-compact on context threshold, export transcripts
Semantic Code Search - Vector-indexed codebase for intelligent context retrieval
LSP Integration - Go-to-definition, find references, hover info, and diagnostics
Memory System - Persistent memories across sessions
MCP Integration - Extend capabilities with Model Context Protocol servers
Custom Commands & Agents - Define your own slash commands and specialized agents
Favorite Models - Star frequently used models for quick access
IDE Extensions - JSON-RPC server mode for VS Code and JetBrains integration
Custom Ignore File - .aimagicxignore for project-specific file exclusions
Auto-Update - Automatic daily update checks with self-installation

Installation

# Install globally
npm install -g aimagicx-cli

# Or with pnpm
pnpm add -g aimagicx-cli

Quick Start

# Start the TUI (opens provider connect if not authenticated)
aimagicx

# Or explicitly start chat
aimagicx chat

# With a specific model
aimagicx chat -m gpt-4o

# Resume a previous session
aimagicx -r <session-id>

Keyboard Shortcuts

Global Shortcuts

| Shortcut | Action | |----------|--------| | ctrl+l | Switch model | | ctrl+n | New session | | ctrl+o | Connect provider | | ctrl+c | Cancel current operation (2x to quit) | | ctrl+w | Quit immediately | | ctrl+z | Undo last file change | | ctrl+y | Redo last undone change | | ctrl+x | Toggle expand/collapse messages | | Esc Esc | Rewind to last checkpoint | | Tab | Cycle approval mode (read-only → auto → full) | | Shift+Tab | Cycle modes (Agent → Review → Plan) | | Alt+T | Toggle task panel (show/hide todos) | | / | Open command palette | | @ | Attach file | | # | Save/attach memory | | $ | Save/insert snippet | | * | Toggle favorite (in model selector) |

Input Shortcuts

| Shortcut | Action | |----------|--------| | ctrl+u | Clear input line | | Escape | Clear input (if not empty) | | ctrl+a | Jump to beginning of line | | ctrl+e | Jump to end of line | | ctrl+n | Insert new line (multiline input) | | ↑ / ↓ | Navigate input history | | ← / → | Move cursor | | ctrl+shift+v | Paste text (terminal standard) |

Commands

Authentication

# Login with API key
aimagicx auth login
aimagicx auth login --provider anthropic

# Check auth status
aimagicx auth status

# Logout
aimagicx auth logout
aimagicx auth logout --provider openai

Chat

# Start interactive chat
aimagicx chat

# Use specific model
aimagicx chat -m claude-sonnet-4-20250514

# Resume previous session
aimagicx chat -r <session-id>

# One-shot prompt
aimagicx chat -p "Explain this codebase"

# Set approval mode
aimagicx chat -a read-only    # Read-only mode (exploration only)
aimagicx chat -a auto         # Auto mode (default, confirmations for changes)
aimagicx chat -a full         # Full mode (auto-approve all operations)
aimagicx chat --yolo          # Alias for --approval-mode full

# Skip confirmations (legacy, same as --yolo)
aimagicx chat --no-confirm

# Headless mode (for automation/scripts)
aimagicx chat -p "Fix the bug" --headless

Providers

# List configured providers
aimagicx provider list

# Show available presets
aimagicx provider presets

# Add provider from preset
aimagicx provider add anthropic --preset anthropic

# Add custom provider
aimagicx provider add my-provider \
  --endpoint https://api.example.com/v1 \
  --protocol openai \
  --model gpt-4

# Switch active provider
aimagicx provider use anthropic

# Remove provider
aimagicx provider remove openai

Sessions

# List sessions
aimagicx session list
aimagicx session list --all

# Resume session
aimagicx session resume <session-id>

# Rename session
aimagicx session rename <session-id> "Feature Implementation"

# Compact session (reduce context)
aimagicx session compact <session-id>

# Export session
aimagicx session export <session-id> --format markdown
aimagicx session export <session-id> --format json

# Delete session
aimagicx session delete <session-id>

Configuration

# Show all config
aimagicx config list

# Get specific value
aimagicx config get defaultModel

# Set value
aimagicx config set maxTokens 8192
aimagicx config set autoConfirmWrites true

# Initialize project config
aimagicx config init

# Show config paths
aimagicx config path

# Reset to defaults
aimagicx config reset

Index (Semantic Search)

# Build vector index
aimagicx index build

# Check index status
aimagicx index status

# Search codebase
aimagicx index search "authentication logic"

Shell Completions

# Bash
aimagicx completion bash >> ~/.bashrc
# Or
aimagicx completion bash > /etc/bash_completion.d/aimagicx

# Zsh
mkdir -p ~/.zsh/completions
aimagicx completion zsh > ~/.zsh/completions/_aimagicx
# Add to ~/.zshrc:
#   fpath=(~/.zsh/completions $fpath)
#   autoload -Uz compinit && compinit

# Fish
mkdir -p ~/.config/fish/completions
aimagicx completion fish > ~/.config/fish/completions/aimagicx.fish


  # Type aimagicx and press Tab - shows all commands
  aimagicx <Tab>
  # Shows: auth, chat, config, provider, session, index, doctor, completion, usage

  # Type partial command and Tab to complete
  aimagicx pro<Tab>
  # Completes to: aimagicx provider

  # Tab again to see subcommands
  aimagicx provider <Tab>
  # Shows: list, add, remove, use, presets

  # Works with options too
  aimagicx chat --<Tab>
  # Shows: --model, --resume, --no-confirm

  # Double Tab shows all options
  aimagicx session <Tab><Tab>
  # Shows: list, resume, rename, compact, export, delete

Update

# Check for updates and install if available
aimagicx update

Other Commands

# Check API quota/usage
aimagicx usage

# Run diagnostics
aimagicx doctor

# Start server for IDE extensions
aimagicx serve

In-Chat Commands

Type / to open the command palette, or use these directly:

| Command | Description | |---------|-------------| | /new-session | Start new session | | /session-list | List sessions | | /compact | Summarize conversation to reduce context | | /switch-model | Switch model | | /provider-connect | Connect a provider | | /config-global | Open global config directory | | /config-project | Open project config directory | | /config-project-init | Initialize project config | | /index-build | Build semantic search index | | /index-status | Show index status | | /memories | List saved memories | | /commit | Generate AI commit message | | /diff | Show git status/diff | | /undo | Undo last file change | | /redo | Redo last undone change | | /history | Show recent file changes | | /tools | Open Tool Manager (enable/disable tools) | | /tools-list | List all available tools | | /review | Toggle Review Mode | | /expand-toggle | Toggle expand/collapse messages | | /context-init-project | Create AIMAGICX.md in project | | /context-init-global | Create ~/.aimagicx/AIMAGICX.md | | /context-reload | Reload AIMAGICX.md files | | /context-show | Show loaded context files | | /checkpoint | Create manual checkpoint | | /rewind | Rewind to last checkpoint | | /checkpoint-list | List saved checkpoints | | /snippets | List saved snippets | | /mcp-status | Show MCP server status | | /mcp-connect | Connect MCP servers | | /mcp-disconnect | Disconnect MCP servers | | /spawn | Spawn a background task | | /tasks | List background tasks | | /task-kill | Kill a running task | | /task-cleanup | Remove completed tasks | | /todos-toggle | Toggle task panel visibility | | /loadtodos | Load todos from current session | | /cleartodos | Clear all todos | | /approval-mode | Cycle approval mode | | /quota | Show API quota/balance | | /doctor | Run diagnostics | | /tools | List available tools | | /usage | Show token usage | | /context | Show context status | | /help | Show keyboard shortcuts | | /quit | Exit chat |

Configuration

Config Locations

| Type | Location | |------|----------| | Global config | ~/.aimagicx/config.json | | Project config | .aimagicx/config.json | | Credentials | ~/.aimagicx/credentials.d/ | | OAuth tokens | ~/.aimagicx/oauth/ | | Sessions | ~/.aimagicx/sessions/ | | Memories | ~/.aimagicx/memory/ (global) or .aimagicx/memory/ (project) | | Vector Index | .aimagicx/index/ | | Custom Commands | ~/.aimagicx/commands.json | | Custom Agents | ~/.aimagicx/agents.json | | MCP Servers | ~/.aimagicx/mcp.json | | LSP Servers | ~/.aimagicx/lsp.json | | Checkpoints | .aimagicx/checkpoints/ | | Context Files | AIMAGICX.md (project root) or ~/.aimagicx/AIMAGICX.md (global) | | Ignore Patterns | .aimagicxignore (project) or ~/.aimagicx/ignore (global) |

Config Hierarchy

Global-only settings (always from ~/.aimagicx/config.json):
- favoriteModels - Your starred models
- providers - Provider configurations
- currentProvider - Active provider
Project-overridable settings (project config overrides global):
- defaultModel, maxTokens, maxToolIterations, etc.

Config Options

{
  "apiEndpoint": "https://api.anthropic.com/v1",
  "apiProtocol": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514",
  "maxTokens": 16384,
  "maxToolIterations": 10,
  "autoConfirmWrites": false,
  "showTokenUsage": true,
  "contextThreshold": 0.9,
  "autoCompactEnabled": true,
  "autoSaveEnabled": true,
  "useVectorIndex": true,
  "maxContextChunks": 10,
  "maxContextTokens": 8000,
  "minContextScore": 0.15,
  "preferredModels": ["claude-sonnet-4-20250514", "gpt-4o"],
  "favoriteModels": ["gpt-4o", "claude-sonnet-4-20250514"],
  "allowedReadRoots": [],
  "disabledTools": [],
  "reviewMode": false,
  "approvalMode": "auto"
}

Key Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | defaultModel | string | - | Default model to use | | maxTokens | number | 16384 | Maximum tokens per request | | maxToolIterations | number | 10 | Max tool calls per response (1-50) | | autoConfirmWrites | boolean | false | Skip confirmation for file operations | | showTokenUsage | boolean | true | Display token usage after requests | | contextThreshold | number | 0.9 | Auto-compact when context usage exceeds this (0-1) | | autoCompactEnabled | boolean | true | Enable auto-compaction on context threshold | | useVectorIndex | boolean | true | Enable semantic code search | | maxContextChunks | number | 10 | Max code chunks to include in context | | maxContextTokens | number | 8000 | Max tokens for retrieved context | | minContextScore | number | 0.15 | Minimum relevance score for context chunks | | favoriteModels | string[] | [] | Models marked as favorites (shown first) | | allowedReadRoots | string[] | [] | Restrict file access to these paths | | disabledTools | string[] | [] | Tools disabled by default (use /tools to toggle) | | reviewMode | boolean | false | Start in Review Mode (batch file changes) | | approvalMode | string | "auto" | Default approval mode: read-only, auto, or full | | autoUpdateEnabled | boolean | true | Enable automatic daily update checks |

Supported Providers

Built-in Presets

| Provider | Protocol | Default Model | Auth Method | |----------|----------|---------------|-------------| | Anthropic | anthropic | claude-sonnet-4-5-20250929 | API Key | | OpenAI | openai | gpt-4o-mini | API Key | | GitHub Copilot | openai | gpt-4o | OAuth Device Flow | | OpenRouter | openai | openai/gpt-4o-mini | API Key | | Groq | openai | moonshotai/kimi-k2-instruct-0905 | API Key | | GitHub Models | openai | gpt-4o-mini | API Key | | Z.ai | openai | GLM-4.7 | API Key | | AI Magicx | aimagicx | openai/gpt-oss-120b | API Key |

GitHub Copilot

GitHub Copilot uses OAuth device flow for authentication:

Select "GitHub Copilot" from provider connect (ctrl+o)
A device code will be displayed
Open the verification URL in your browser
Enter the code and authorize
Token is automatically refreshed when expired

Adding Custom Providers

Any OpenAI-compatible API can be added:

aimagicx provider add ollama \
  --endpoint http://localhost:11434/v1 \
  --protocol openai \
  --model llama3.2

Model Selector

Press ctrl+l to open the model selector:

Search - Type to filter models by name, ID, or provider
Navigate - Arrow keys to move, Enter to select
Favorite - Press * to star/unstar a model
Connect - Press ctrl+o to add a new provider

Favorite models appear at the top in a dedicated section.

Agent Tools

The AI agent has access to these tools:

| Tool | Description | |------|-------------| | read | Read file contents with line numbers | | write | Create new files | | edit | Modify existing files (string replacement) | | apply_patch | Apply unified diff patches (create/modify/delete files) | | glob | Find files by pattern | | grep | Search file contents with regex | | bash | Execute shell commands | | list_directory | List directory contents | | web_search | Search the web | | web_fetch | Fetch and analyze web pages | | vector_search | Semantic code search using embeddings | | vision | Read and analyze images (PNG, JPG, GIF, WebP) | | multi_tool_use.parallel | Execute multiple tools in parallel | | save_memory | Save persistent memories | | read_memory | Retrieve saved memories | | lsp_goto_definition | Navigate to symbol definition | | lsp_find_references | Find all references to a symbol | | lsp_hover | Get type information and documentation | | lsp_diagnostics | Get file errors/warnings from LSP server | | todos | Track progress on multi-step tasks | | spawn_agent | Spawn specialized subagents (explorer, planner, background, reviewer) |

Tool Modes

Agent Mode (default) - Full access to all tools including write/edit/bash
Review Mode - Like Agent but collects file changes for batch review when complete
Plan Mode - Read-only tools for exploration and planning

Toggle with Shift+Tab (cycles: Agent → Review → Plan → Agent).

Approval Modes

Approval modes control how much autonomy the agent has over tool execution:

| Mode | Description | Use Case | |------|-------------|----------| | read-only | Only exploration tools (read, glob, grep, etc.) | Safe exploration, code review | | auto | Confirmations for file changes and shell commands | Normal development (default) | | full | Auto-approve all operations | Trusted automation, scripting |

Changing Approval Mode

Keyboard: Press Tab to cycle through modes

Command Palette: /approval-mode

CLI Flag:

aimagicx chat -a read-only
aimagicx chat -a auto
aimagicx chat -a full
aimagicx chat --yolo  # Alias for -a full

Config:

{
  "approvalMode": "auto"
}

Permission Details

| Tool Category | read-only | auto | full | |--------------|-----------|------|------| | Read operations (read, glob, grep) | Auto | Auto | Auto | | Write operations (write, edit) | Blocked | Confirm | Auto | | Shell commands (bash) | Blocked | Confirm | Auto* | | MCP tools | Blocked | Confirm | Auto |

*Dangerous bash commands (rm -rf, sudo, etc.) still require confirmation even in full mode.

Background Tasks (Subagents)

Spawn parallel agents to work on tasks concurrently while you continue in the main session.

Commands

| Command | Description | |---------|-------------| | /spawn | Open spawn mode, then type your task | | /spawn <prompt> | Spawn a task directly | | /tasks | List all background tasks with status | | /task-kill | Kill a running task | | /task-kill <id> | Kill a specific task by ID | | /task-cleanup | Remove completed/failed tasks |

Usage Examples

# Spawn a task to run tests in background
/spawn Run all tests and fix any failures

# Spawn a task to build documentation
/spawn Generate API documentation for src/api/

# List running tasks
/tasks

# Kill the only running task
/task-kill

# Kill a specific task
/task-kill abc123

Task Status

| Status | Icon | Description | |--------|------|-------------| | pending | ⏳ | Task queued, waiting to start | | running | 🔄 | Task actively executing | | completed | ✅ | Task finished successfully | | failed | ❌ | Task encountered an error | | cancelled | ⏹️ | Task was manually stopped |

Notes

Maximum 3 concurrent tasks by default
Tasks inherit the current approval mode
Task progress is shown in the status bar
Background tasks cannot prompt for confirmations (auto-denied if not in full mode)

Task Management (Todos)

The AI agent can track progress on complex, multi-step tasks using the todos tool. This helps organize work and shows real-time progress.

Task Panel

A collapsible panel displays current tasks:

Collapsed: Shows task count and active status in a compact bar
Expanded: Shows full task list with status indicators
Toggle: Press Alt+T or use /todos-toggle

Status Indicators

| Status | Icon | Description | |--------|------|-------------| | pending | ○ | Task not yet started | | in_progress | ◐ | Currently working on | | completed | ● | Task finished |

When Todos Are Used

The AI automatically uses todos for:

Multi-step tasks: When a task requires 3+ distinct steps
Complex implementations: Features requiring multiple files or components
User-provided lists: When given a numbered or comma-separated list of things to do

Commands

| Command | Description | |---------|-------------| | Alt+T | Toggle task panel visibility | | /todos-toggle | Toggle task panel (same as Alt+T) | | /loadtodos | Reload todos from current session | | /cleartodos | Clear all todos |

Session Persistence

Todos are stored per-session and auto-load when resuming a session, so you can pick up where you left off.

Automated Subagent Spawning

The AI can automatically spawn specialized agents using the spawn_agent tool to handle complex tasks autonomously.

Agent Types

| Type | Use Case | Example | |------|----------|---------| | explorer | Deep codebase exploration | "Find how authentication is implemented" | | planner | Implementation planning | "Plan how to add caching to the API" | | background | Long-running tasks | "Run all tests and fix any failures" | | reviewer | Code review | "Review the changes in src/auth/*.ts" |

How It Works

Background by default: Agents run in background so the main conversation continues
Monitor progress: Use /tasks to check status
Wait when needed: Use wait: true for tasks where you need the result before continuing (e.g., getting a plan before implementing)

Examples

# AI spawns explorer to understand codebase
spawn_agent: {"agent_type": "explorer", "task": "Find all authentication middleware"}

# AI spawns planner and waits for result
spawn_agent: {"agent_type": "planner", "task": "Plan user profile feature", "wait": true}

# AI spawns reviewer after making changes
spawn_agent: {"agent_type": "reviewer", "task": "Review changes in src/components/"}

Agent vs Manual Subagent

| Feature | spawn_agent (AI-triggered) | /spawn (User-triggered) | |---------|------------------------------|---------------------------| | Initiated by | AI agent | User command | | System prompt | Specialized per agent type | Generic | | Default mode | Background | Foreground | | Use case | AI autonomy | User delegation |

Tool Whitelisting

Enable or disable specific tools:

/tools - Open interactive Tool Manager modal
/tools-list - View all available tools with status
Type to filter, Enter/Space to toggle, j/k to navigate

Config (~/.aimagicx/config.json):

{
  "disabledTools": ["bash", "write"]
}

Disabled tools won't be available to the agent until re-enabled.

Undo/Redo & Checkpoints

AI Magicx tracks all file changes and allows you to revert them.

Quick Undo/Redo

ctrl+z - Undo last file change
ctrl+y - Redo last undone change
/history - View recent file changes

Checkpoints

Checkpoints save the state of modified files for larger rollbacks:

Automatic checkpoints are created before each file modification
Esc Esc (double escape) - Quickly rewind to last checkpoint
/checkpoint - Create a manual checkpoint
/checkpoint-list - View all checkpoints
/rewind - Restore the most recent checkpoint

Checkpoints are stored in .aimagicx/checkpoints/ (up to 50 per project).

Context Files (AIMAGICX.md)

Create AIMAGICX.md files to provide persistent context to the AI:

Locations (all are loaded)

~/.aimagicx/AIMAGICX.md - Global context (all projects)
./AIMAGICX.md - Project root
./src/AIMAGICX.md - Subdirectory context

Example AIMAGICX.md

# Project: E-commerce API

## Architecture
- Node.js with Express
- PostgreSQL with Prisma ORM
- Redis for caching

## Conventions
- All prices stored in cents (integers)
- Use snake_case for database columns
- Use camelCase for JavaScript

## Important
- Never modify files in `src/legacy/`
- All API responses use the standard wrapper

@docs/api-reference.md

The @path/to/file.md syntax imports content from other markdown files.

Commands:

/context-show - View loaded context files
/context-reload - Reload after changes

Memory System

Save important information that persists across sessions:

# In chat, use # prefix to save memories
#project-context This is a React app using TypeScript...

# Or use the memory picker
# (type # with empty input to open picker)

Memories are stored as markdown files:

Global: ~/.aimagicx/memory/
Project: .aimagicx/memory/

Snippets

Save and reuse code snippets:

# Save a snippet
$snippet-name Your code here...

# Insert a snippet (type $ with empty input)
# Opens snippet picker

Snippets are stored in ~/.aimagicx/snippets/.

Semantic Code Search

Build a vector index of your codebase for intelligent context retrieval:

# Build index
aimagicx index build

# The agent will automatically use relevant code context

Configuration:

{
  "useVectorIndex": true,
  "maxContextChunks": 10,
  "maxContextTokens": 8000,
  "minContextScore": 0.15
}

Custom Commands

Create custom slash commands in ~/.aimagicx/commands.json:

{
  "commands": [
    {
      "id": "review",
      "name": "Code Review",
      "description": "Review current file",
      "type": "prompt",
      "content": "Review this code for bugs, security issues, and best practices:\n\n{{input}}"
    },
    {
      "id": "test",
      "name": "Generate Tests",
      "description": "Generate tests for code",
      "type": "prompt",
      "content": "Generate comprehensive tests for:\n\n{{input}}"
    },
    {
      "id": "git-log",
      "name": "Git Log",
      "description": "Recent commits",
      "type": "bash",
      "content": "git log --oneline -10",
      "showOutput": true
    }
  ]
}

Custom Agents

Define specialized agents in ~/.aimagicx/agents.json:

{
  "agents": [
    {
      "id": "reviewer",
      "name": "Code Reviewer",
      "icon": "🔍",
      "description": "Code review specialist",
      "systemPrompt": "You are an expert code reviewer. Focus on bugs, security, performance, and best practices.",
      "model": "claude-sonnet-4-20250514",
      "includeContext": true
    },
    {
      "id": "architect",
      "name": "System Architect",
      "icon": "🏗️",
      "description": "System design expert",
      "systemPrompt": "You are a software architect. Help design scalable, maintainable systems.",
      "tools": ["read", "glob", "grep", "list_directory"]
    }
  ]
}

Activate agents from the command palette (/).

MCP Integration

Connect Model Context Protocol servers for extended capabilities.

Configure in ~/.aimagicx/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

Use /mcp-status, /mcp-connect, /mcp-disconnect to manage servers.

LSP Integration

AI Magicx integrates with Language Server Protocol (LSP) servers for intelligent code understanding.

LSP Tools

The AI agent can use these LSP-powered tools:

| Tool | Description | |------|-------------| | lsp_goto_definition | Navigate to where a symbol is defined | | lsp_find_references | Find all usages of a symbol across the codebase | | lsp_hover | Get type signatures and documentation | | lsp_diagnostics | Get compiler errors, warnings, and linting issues |

Configuration

Configure LSP servers in ~/.aimagicx/lsp.json:

{
  "servers": [
    {
      "name": "typescript",
      "languages": [".ts", ".tsx", ".js", ".jsx"],
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "enabled": true
    },
    {
      "name": "python",
      "languages": [".py", ".pyi"],
      "command": "pylsp",
      "args": [],
      "enabled": true
    }
  ],
  "autoDetect": true,
  "autoStart": true
}

Default Servers

| Language | Server | File Extensions | |----------|--------|-----------------| | TypeScript/JavaScript | typescript-language-server | .ts, .tsx, .js, .jsx, .mjs, .cjs | | Python | pylsp | .py, .pyi | | Go | gopls | .go | | Rust | rust-analyzer | .rs | | JSON | vscode-json-language-server | .json, .jsonc | | YAML | yaml-language-server | .yaml, .yml | | CSS | vscode-css-language-server | .css, .scss, .less | | HTML | vscode-html-language-server | .html, .htm |

Installing LSP Servers

# TypeScript/JavaScript
npm install -g typescript-language-server typescript

# Python
pip install python-lsp-server

# Go
go install golang.org/x/tools/gopls@latest

# Rust
rustup component add rust-analyzer

Servers are auto-started when needed and auto-detected based on file extensions.

Custom Ignore File

Control which files AI Magicx ignores when searching and indexing.

File Locations

Project-level: .aimagicxignore in project root
Global: ~/.aimagicx/ignore

Both support gitignore syntax, including negation patterns.

Example `.aimagicxignore`

# Large data files
*.csv
*.parquet
data/

# Test fixtures
__fixtures__/
*.snap

# Generated files
dist/
build/
*.generated.ts

# Sensitive files
.env*
secrets/

# But keep this vendor directory
!important-vendor/

Default Patterns

These are always ignored (built-in):

Directories: node_modules, .git, dist, build, .next, coverage, __pycache__, .venv, target
Binary files: *.png, *.jpg, *.gif, *.ico, *.woff, *.ttf, *.pdf, *.zip
Lock files: package-lock.json, pnpm-lock.yaml, yarn.lock
Minified files: *.min.js, *.min.css

The ignore system applies to the glob and grep tools used by the AI agent.

IDE Extensions (Server Mode)

AI Magicx can run as a JSON-RPC server for integration with IDEs like VS Code and JetBrains.

Starting the Server

# Start server in stdio mode
aimagicx serve

Protocol

The server uses JSON-RPC 2.0 over stdio with Content-Length headers.

Requests

| Method | Description | |--------|-------------| | initialize | Initialize with project path and capabilities | | chat | Send a message and receive streaming response | | tool/confirm | Confirm or deny a tool execution | | session/list | List available sessions | | abort | Cancel current operation | | shutdown | Gracefully shutdown the server |

Notifications (Server → Client)

| Method | Description | |--------|-------------| | $/text | Streaming text content | | $/toolCall | Tool about to be executed | | $/toolResult | Tool execution completed | | $/error | Error occurred | | $/progress | Progress update |

Example: Initialize

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "projectPath": "/path/to/project",
    "clientName": "vscode",
    "clientVersion": "1.0.0"
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "serverVersion": "0.1.0",
    "capabilities": {
      "tools": ["read", "write", "edit", "glob", "grep", "bash", "..."],
      "streaming": true,
      "sessions": true,
      "lsp": true
    }
  }
}

Example: Chat

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "chat",
  "params": {
    "message": "Add a logout button to the header",
    "sessionId": "optional-session-id"
  }
}

Notifications received:

{"jsonrpc": "2.0", "method": "$/text", "params": {"content": "I'll add a logout button...", "done": false}}
{"jsonrpc": "2.0", "method": "$/toolCall", "params": {"requestId": "uuid", "name": "edit", "arguments": {...}}}
{"jsonrpc": "2.0", "method": "$/toolResult", "params": {"requestId": "uuid", "name": "edit", "success": true}}
{"jsonrpc": "2.0", "method": "$/text", "params": {"content": "", "done": true}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "sessionId": "session-uuid"
  }
}

VS Code Extension Example

import { spawn } from 'child_process';

const server = spawn('aimagicx', ['serve'], {
  cwd: workspaceRoot,
  stdio: ['pipe', 'pipe', 'pipe']
});

// Send request
function sendRequest(method: string, params: any) {
  const content = JSON.stringify({
    jsonrpc: '2.0',
    id: nextId++,
    method,
    params
  });
  const message = `Content-Length: ${Buffer.byteLength(content)}\r\n\r\n${content}`;
  server.stdin.write(message);
}

// Handle responses and notifications
server.stdout.on('data', (data) => {
  // Parse JSON-RPC messages...
});

// Initialize
sendRequest('initialize', { projectPath: workspaceRoot });

// Chat
sendRequest('chat', { message: 'Fix the bug in auth.ts' });

UI Features

Performance Optimizations

AI Magicx is optimized for smooth, flicker-free terminal rendering:

Adaptive streaming throttle - Dynamically adjusts buffer timing based on chunk rate
Isolated spinner animations - Status bar spinners don't trigger parent re-renders
Memoized components - Input, StatusBar, and Markdown components use React.memo
LRU cache for markdown - Parsed markdown is cached to avoid re-parsing
Native terminal scrollback - Uses terminal's built-in scroll for mouse wheel support

Status Indicators

Animated spinner while thinking or executing tools
Context usage percentage in status bar
Mode indicator (Agent/Review/Plan) with color coding
Provider and model display

Provider Connect

The provider connect dialog shows authentication status:

✓ authenticated - Provider has valid API key
○ needs key - Provider needs authentication

Security

File Access

Use allowedReadRoots to restrict file access to specific directories
Write/edit operations require confirmation (unless autoConfirmWrites: true)
Dangerous bash commands are blocked by default

Credentials

API keys are stored with restricted permissions (0600)
OAuth tokens stored separately in ~/.aimagicx/oauth/
Keys are never logged or displayed in full
Support for environment variable fallback (AIMAGICX_API_KEY)

Blocked Commands

The following patterns are blocked in bash:

rm -rf / and system path deletions
shutdown, reboot, halt, poweroff
Fork bombs
Device file writes

Environment Variables

| Variable | Description | |----------|-------------| | AIMAGICX_API_KEY | Default API key (fallback) | | AIMAGICX_CONFIG_DIR | Custom config directory | | NO_COLOR | Disable colored output |

Telemetry

AI Magicx collects anonymous usage data to improve the product. This is completely optional and can be disabled.

What We Collect

CLI version, platform, and Node.js version
Session duration, message count, and token usage
Tool execution (name, success/failure, duration)
Feature usage (vector index, compaction, etc.)
Error types (no sensitive data)

What We DON'T Collect

File paths or code content
Prompts or conversations
API keys or credentials
Any personally identifiable information

Opting Out

aimagicx config set telemetryEnabled false

Usage Examples & Use Cases

Daily Development Workflows

Starting a New Feature

# Start with read-only mode to explore first
aimagicx chat -a read-only
> "Explain how authentication works in this codebase"
> "What files would I need to modify to add a logout feature?"

# Once you understand, switch to auto mode (Tab key or restart)
aimagicx chat
> "Add a logout button to the header component"

Bug Fixing

# Attach the error log or screenshot
aimagicx chat
> @error.log "Fix this error"

# Or describe the issue
> "The login form submits twice when clicking the button"

Code Review

# Use read-only mode to safely explore changes
aimagicx chat -a read-only
> "Review the changes in src/auth/*.ts for security issues"

# Or use Review Mode for batch reviewing AI changes
# Press Shift+Tab to switch to Review Mode

Refactoring

aimagicx chat
> "Refactor the UserService class to use dependency injection"
> "Extract the validation logic from UserController into a separate module"

Automation & Scripting

CI/CD Integration

# Headless mode for automated pipelines
aimagicx chat -p "Fix any TypeScript errors in src/" --headless -a full

# One-shot commands for scripts
aimagicx chat -p "Generate a changelog from recent commits" --headless

Batch Operations

# Use full approval mode for trusted batch operations
aimagicx chat -a full
> "Add JSDoc comments to all exported functions in src/utils/"
> "Update all imports from 'lodash' to use named imports"

Learning & Exploration

Understanding a New Codebase

aimagicx chat -a read-only
> "Give me an overview of this project's architecture"
> "What are the main entry points?"
> "How does data flow from the API to the UI?"

Learning Patterns

> "Explain the error handling pattern used in this codebase"
> "Show me examples of how tests are structured here"

Best Practices

1. Start in Read-Only Mode for Unfamiliar Code

# Safe exploration - no accidental changes
aimagicx chat -a read-only

Why: Prevents accidental modifications while you understand the codebase. Switch to auto mode once you're ready to make changes.

2. Use AIMAGICX.md for Project Context

Create a AIMAGICX.md in your project root:

# Project: My App

## Architecture
- React frontend with TypeScript
- Express backend with PostgreSQL
- Redis for session management

## Conventions
- Use functional components with hooks
- All API responses follow { data, error, meta } format
- Database column names use snake_case

## Do NOT modify
- src/legacy/ (deprecated, scheduled for removal)
- migrations/ (use CLI to generate new migrations)

## Testing
- Run `pnpm test` before committing
- Integration tests require `docker-compose up -d`

Why: The AI reads this context on every request, ensuring consistent understanding of your project's standards.

3. Build the Vector Index for Large Codebases

aimagicx index build

Why: Semantic search helps the AI find relevant code even when you don't know exact file names or function names.

4. Use Sessions for Complex Tasks

# Name your sessions for easy resumption
aimagicx chat
# Work on a feature...

# Later, resume where you left off
aimagicx session list
aimagicx chat -r <session-id>

Why: Sessions preserve context, so the AI remembers previous discussions and decisions.

5. Use Background Tasks for Long Operations

# Don't block your main session
/spawn Run all tests and fix any failures
/spawn Generate API documentation

# Continue working while tasks run
/tasks  # Check progress

Why: Background tasks let you stay productive while the AI handles time-consuming operations.

6. Leverage Checkpoints Before Major Changes

# Create a checkpoint before risky changes
/checkpoint

# If something goes wrong
/rewind
# Or double-press Escape

Why: Checkpoints provide a safety net for reverting multiple file changes at once.

7. Use Specific, Actionable Prompts

GOOD: "Add input validation to the signup form: email must be valid,
       password must be 8+ characters with one number"

BAD:  "Make the form better"

Why: Specific prompts lead to predictable results. Vague prompts may produce unexpected changes.

8. Review Changes Before Committing

# Always check what changed
/diff
git diff

# Use undo if needed
ctrl+z  # or /undo

Why: Even in full approval mode, reviewing changes before committing ensures quality.

Common Pitfalls & What to Avoid

1. Don't Use Full Mode on Untrusted Projects

# RISKY: Auto-approves everything including shell commands
aimagicx chat -a full  # in an unfamiliar codebase

Better: Start with auto mode and upgrade to full only when you trust the operations.

2. Don't Ignore Context Warnings

When you see high context usage (80%+):

# Compact the session to free up context
/compact

Why: Running out of context causes the AI to lose earlier conversation details, leading to inconsistent responses.

3. Don't Skip Reading the Suggested Changes

# The AI shows you what it's about to do - READ IT
# [edit] src/auth/login.ts
# - const token = jwt.sign(user)
# + const token = jwt.sign(user, { expiresIn: '24h' })

Why: Blindly accepting changes can introduce bugs or security issues.

4. Don't Forget to Save Memories for Important Context

# Save project-specific knowledge
#api-format All API responses use { success, data, error } format
#auth-flow Authentication uses JWT with refresh tokens

Why: Memories persist across sessions, so you don't need to re-explain project conventions.

5. Don't Leave Sensitive Data in Sessions

Sessions are stored locally. If you've discussed sensitive information:

# Delete the session when done
aimagicx session delete <session-id>

6. Don't Run Without Testing After Changes

# Always verify changes work
> "Run the tests to make sure nothing broke"

# Or spawn a background task
/spawn Run tests and report any failures

7. Don't Overload a Single Prompt

# TOO MUCH at once
> "Add authentication, implement the dashboard, set up the database,
   write tests, add documentation, and deploy to production"

# BETTER: Break into steps
> "Add user authentication with JWT"
# Wait for completion
> "Implement the user dashboard"
# And so on...

Why: Complex prompts can lead to partial implementations or missed requirements.

8. Don't Forget About .aimagicxignore

# .aimagicxignore
secrets/
*.env*
credentials/
private/

Why: Prevents the AI from reading or accidentally exposing sensitive files.

Tips & Tricks

Quick Mode Switching

Tab - Cycle approval modes (read-only → auto → full)
Shift+Tab - Cycle tool modes (Agent → Review → Plan)

Efficient File Attachment

# Attach files with context
@src/auth/login.ts "Fix the token expiry issue"
@package.json @tsconfig.json "Update TypeScript to version 5"

Multi-Line Prompts

# Press Ctrl+N to insert newlines
> First line of my prompt
  Second line with more context  # Ctrl+N before this
  Third line with requirements

Quick Commands

# Type / to open command palette with fuzzy search
/com  # matches /compact, /commit
/sw   # matches /switch-model

Star Your Favorite Models

# Press * in the model selector to star/unstar
# Starred models appear at the top
ctrl+l → * → Enter

Export Sessions for Documentation

# Export as markdown for documentation
aimagicx session export <id> --format markdown > feature-implementation.md

# Export as JSON for analysis
aimagicx session export <id> --format json > session.json

Use Glob Patterns in Questions

> "Review all test files in src/**/*.test.ts"
> "Find any TODO comments in src/components/*.tsx"

Troubleshooting

Run Diagnostics

aimagicx doctor

Common Issues

"Not authenticated"

aimagicx auth login --provider <provider-name>
# Or use ctrl+o in chat to connect

"Model not found"

Check model name matches provider's naming
Use aimagicx provider presets to see default models
Ensure the model is in your preferredModels or fetched from API

"Authentication failed" for GitHub Copilot

Copilot tokens expire quickly (~30 min)
Token refresh is automatic if OAuth token is valid
If issues persist, reconnect with ctrl+o

High context usage

# Compact the session
aimagicx session compact <session-id>

# Or in chat
/compact

# Auto-compact triggers at contextThreshold (default 90%)

Favorites not showing

Favorites are stored in global config (~/.aimagicx/config.json)
Project config doesn't override favoriteModels

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

AI Magicx CLI

Table of Contents

Features

Installation

Quick Start

Keyboard Shortcuts

Global Shortcuts

Input Shortcuts

Commands

Authentication

Chat

Providers

Sessions

Configuration

Index (Semantic Search)

Shell Completions

Update

Other Commands

In-Chat Commands

Configuration

Config Locations

Config Hierarchy

Config Options

Key Options

Supported Providers

Built-in Presets

GitHub Copilot

Adding Custom Providers

Model Selector

Agent Tools

Tool Modes

Approval Modes

Changing Approval Mode

Permission Details

Background Tasks (Subagents)

Commands

Usage Examples

Task Status

Notes

Task Management (Todos)

Task Panel

Status Indicators

When Todos Are Used

Commands

Session Persistence

Automated Subagent Spawning

Agent Types

How It Works

Examples

Agent vs Manual Subagent

Tool Whitelisting

Undo/Redo & Checkpoints

Quick Undo/Redo

Checkpoints

Context Files (AIMAGICX.md)

Locations (all are loaded)

Example AIMAGICX.md

Memory System

Snippets

Semantic Code Search

Custom Commands

Custom Agents

MCP Integration

LSP Integration

LSP Tools

Configuration

Default Servers

Installing LSP Servers

Custom Ignore File

File Locations

Example .aimagicxignore

Default Patterns

IDE Extensions (Server Mode)

Starting the Server

Example `.aimagicxignore`