UltraAgent

Autonomous AI coding assistant with Superpowers — powered by local LLMs on Apple Silicon.

Getting Started · Commands · Tool System · Superpowers · Project Creation · Configuration

What is UltraAgent?

UltraAgent is a terminal-based AI coding assistant that operates autonomously using an integrated tool system. It reads, writes, and edits files, runs shell commands, searches codebases, manages git, spawns sub-agents, persists memory, and browses the web — all controlled by a configurable three-tier permission system.

Runs 100% local on your machine — no API keys, no cloud, no data leaves your computer. Supports Ollama, LM Studio, MLX-LM, and llama.cpp.

Highlights

• 100% local & private — no API keys, no cloud, all data stays on your machine
• Auto-Setup — detects your hardware, backends, and recommends optimal model + settings
• 36 built-in tools — file I/O, shell, git, sub-agents, memory, web, planning, review, verification
• 14 Superpowers skills — TDD, debugging, code review, worktrees, brainstorming, and more
• Smart model routing — automatically selects the optimal model per task complexity
• Quality gates — validates outputs, catches failure patterns, forces retries on bad responses
• Reasoning engine — chain-of-thought scaffolding that improves local LLM reasoning by 20-40%
• Code review — sub-agent-powered two-stage review (spec compliance + code quality)
• Verification gates — evidence-based completion with automated test/build/lint checks
• Background agents — non-blocking parallel agents that run in the background
• Git worktrees — isolated workspaces for parallel development branches
• Project creation wizard — scaffold production-ready projects from scratch
• Project scanner — deep analysis auto-injected into every LLM request
• Three-tier permissions — safe / confirm / dangerous, user approves before risky ops
• Agentic loop — LLM autonomously selects tools, executes, observes, iterates (up to 30 rounds)
• Sub-agents — spawn parallel agents for concurrent tasks
• Persistent memory — context that survives across sessions
• Apple Silicon optimized — curated model recommendations for M-series chips
• Error tracking — detects repeated error patterns and provides targeted correction prompts
• Real-time streaming — token-by-token output with repetition detection
• Input queue — type-ahead while agent generates, prompts are queued and processed sequentially
• Auto-init — automatically sets up .ultraagent/ on first run in any project
• Text-to-ToolCall parser — catches local models that leak tool calls as JSON text

Getting Started

Install from npm (recommended)

npm install -g ultraagent

That's it. Now go to any project and start:

cd my-project
ua chat              # auto-initializes .ultraagent/ on first run

UltraAgent auto-detects your project type, creates the config, and starts the agent.

Full Setup (with local LLM configuration)

npm install -g ultraagent
ua local setup           # auto-detects hardware, backend, sets optimal config
cd my-project
ua init                  # set up .ultraagent/, scan project, update .gitignore
ua chat                  # start coding

The local setup command automatically:

1. Detects your chip, RAM, GPU cores
2. Finds running backends (LM Studio, Ollama, MLX-LM, llama.cpp)
3. Recommends the best model for your hardware
4. Sets optimal context length, KV-cache, batch size, flash attention
5. Verifies the connection

What ua init creates

my-project/
├── .ultraagent/
│   ├── config.json              ← Project-specific settings
│   ├── mcp.json                 ← MCP server configuration
│   ├── skills/                  ← Custom project skills
│   │   └── project-conventions/
│   │       └── SKILL.md         ← Example skill (customize this)
│   └── plugins/                 ← Custom tool plugins
│       └── README.md
├── docs/
│   └── scan.md                  ← Project scan (auto-injected into every LLM request)
└── .gitignore                   ← Updated with .ultraagent/plugins/, .worktrees/

Auto-init: If you skip ua init, it runs automatically on your first ua chat in any project.

Quick Start (from source)

git clone https://github.com/zurd46/UltraAgent.git
cd UltraAgent
npm install

npm run dev -- local setup    # auto-detects hardware, backend, sets optimal config
npm run dev -- chat           # start coding

Manual Setup

ua config set provider ollama
ua config set localModel qwen2.5-coder:14b
ua chat

Update

npm install -g ultraagent@latest

Alias: ua works everywhere instead of ultraagent.

Supported Backends

Recommended Models (Apple Silicon)

ultraagent models --ram 32    # show recommendations for your RAM

LM Studio Optimal Settings

When using LM Studio, set these in Settings > Server for best performance:

ultraagent local setup sets these values automatically based on your hardware.

Commands

ultraagent <command> [options]

Project

Agent

Quality & Diagnostics

Configuration & Local LLM

Tool System

UltraAgent ships with 36 tools that the LLM invokes autonomously during a session. Each tool has an assigned permission level.

Permission Model

When prompted: [y]es · [n]o · [a]lways allow · [d]eny always

Tools

Superpowers

UltraAgent v2.0 introduces Superpowers — a skill system that gives the agent structured workflows for complex tasks. Skills are loaded automatically based on context or can be invoked explicitly.

Built-in Skills (14)

Custom Skills

Add project-specific skills in .ultraagent/skills/ or global skills in ~/.ultraagent/skills/. Each skill is a directory with a SKILL.md file containing frontmatter and instructions.

Smart Core Modules

Model Router

Automatically routes tasks to the optimal model based on complexity:

Quality Gates

Validates agent outputs and catches common local LLM failure patterns:

• False success claims (says "done" but nothing changed)
• Generic/hallucinated responses
• Test failures ignored
• Hallucinated file paths

Reasoning Engine

Injects chain-of-thought scaffolding tailored to task complexity, improving local LLM reasoning quality by 20-40%.

Error Tracker

Detects repeated error patterns (file-not-found, edit-mismatch, test-failure) and provides targeted correction prompts instead of generic retries.

Verification

Runs automated checks (tests, build, lint, type-check) before accepting completion claims. Auto-detects project type (Node/Rust/Python/Go).

Project Creation

ultraagent new

Interactive wizard that scaffolds complete, production-ready projects.

# Non-interactive
ultraagent new --name my-app --type fullstack --stack nextjs-prisma-pg --prompt "E-commerce platform"

Output

A complete project with directory structure, config files, typed source code, test setup, README, .gitignore, build scripts, initialized git repo, installed dependencies, and auto-generated docs/scan.md.

Project Scanner

ultraagent scan            # scan current project
ultraagent scan --force    # force re-scan
ultraagent scan --dir /path/to/project

Creates docs/scan.md — a comprehensive project analysis that is automatically injected into every LLM request, giving the model full project context.

Cache: scan.md is valid for 24 hours. Use --force to regenerate.

Agent Modes

Switch modes in-session with /mode <mode>.

Session Commands

Hook System

Automate actions before or after tool calls. Config lives in .ultraagent/hooks.json.

{
  "hooks": [
    {
      "timing": "after",
      "tool": "write_file",
      "command": "npx prettier --write ${file}",
      "enabled": true
    },
    {
      "timing": "after",
      "tool": "edit_file",
      "command": "npm test",
      "enabled": true
    }
  ]
}

Variables: ${file} (file path), ${tool} (tool name)

Context Injection

UltraAgent automatically enriches every LLM request with project context:

Priority: Mode prompt > Project context > scan.md > Memories > Plan > History

Custom Instructions

Create ULTRAAGENT.md in your project root:

# Project Instructions
- TypeScript monorepo using pnpm
- Run `pnpm test` after changes
- Use conventional commits

Global instructions: ~/.ultraagent/instructions.md

Configuration

ultraagent local setup                        # auto-detect & configure (recommended)
ultraagent config set provider local-openai
ultraagent config set localModel qwen2.5-coder:14b
ultraagent config show                        # view config
ultraagent config reset                       # reset to defaults

Environment Variables

ULTRAAGENT_PROVIDER=local-openai
ULTRAAGENT_LOCAL_BASE_URL=http://localhost:1234/v1
ULTRAAGENT_LOCAL_MODEL=qwen2.5-coder:14b
ULTRAAGENT_LOCAL_CONTEXT_LENGTH=32768
ULTRAAGENT_LOCAL_TEMPERATURE=0.7
ULTRAAGENT_LOCAL_GPU_LAYERS=-1
ULTRAAGENT_LOCAL_BATCH_SIZE=512
ULTRAAGENT_LOCAL_FLASH_ATTENTION=true
ULTRAAGENT_LOCAL_KV_CACHE_TYPE=q8_0

Architecture

src/
├── cli.ts                    # CLI entry point (Commander.js)
├── index.ts                  # Programmatic API exports
├── commands/                 # Command implementations
│   ├── init.ts               #   Project initialization (auto-runs on first chat)
│   ├── new.ts                #   Project creation wizard
│   ├── scan.ts               #   Project scanner
│   ├── chat.ts               #   Interactive session
│   ├── edit.ts               #   Code editing
│   ├── run.ts                #   Single prompt execution
│   ├── config-cmd.ts         #   Configuration management
│   ├── local.ts              #   Local LLM auto-setup
│   ├── models.ts             #   Model recommendations
│   └── skills-commands/      #   Skill-related CLI commands
├── core/                     # Core engine
│   ├── agent-factory.ts      #   Agent loop, streaming, context injection
│   ├── session.ts            #   Interactive REPL with slash commands
│   ├── context.ts            #   Git context & project instructions
│   ├── context-manager.ts    #   Token-aware history management
│   ├── local-llm.ts          #   Local LLM provider adapters
│   ├── planner.ts            #   Plan creation & task tracking
│   ├── hooks.ts              #   Pre/post tool execution hooks
│   ├── token-tracker.ts      #   Usage tracking
│   ├── undo.ts               #   File change rollback
│   ├── model-router.ts       #   Smart model routing by task complexity
│   ├── quality-gate.ts       #   Output validation & failure pattern detection
│   ├── reasoning-engine.ts   #   Chain-of-thought scaffolding for local LLMs
│   ├── verification.ts       #   Evidence-based completion checks
│   ├── error-tracker.ts      #   Repeated error detection & correction
│   ├── background-agent.ts   #   Non-blocking background agent manager
│   ├── code-reviewer.ts      #   Two-stage code review dispatcher
│   ├── skills.ts             #   Superpowers skill loader & manager
│   ├── mcp-client.ts         #   MCP client for external tool integration
│   ├── plugin-loader.ts      #   Custom plugin loading
│   ├── code-validator.ts     #   Automatic code validation
│   └── session-store.ts      #   Session persistence & restoration
├── skills/                   # Superpowers skill definitions (14 skills)
│   ├── brainstorming/
│   ├── writing-plans/
│   ├── executing-plans/
│   ├── test-driven-development/
│   ├── systematic-debugging/
│   ├── verification-before-completion/
│   ├── requesting-code-review/
│   ├── receiving-code-review/
│   ├── using-git-worktrees/
│   ├── subagent-driven-development/
│   ├── dispatching-parallel-agents/
│   ├── finishing-a-development-branch/
│   ├── writing-skills/
│   └── using-superpowers/
├── tools/                    # Tool system (36 tools)
│   ├── base.ts               #   Registry, permission levels, definitions
│   ├── permissions.ts        #   Permission manager & session allowlist
│   ├── read.ts / write.ts / edit.ts / bash.ts / glob.ts / grep.ts
│   ├── git.ts                #   10 git tools + 2 GitHub tools (gh_pr, gh_issue)
│   ├── sub-agent.ts          #   Parallel sub-agent execution
│   ├── memory.ts             #   memory_save, memory_search, memory_delete
│   ├── web.ts                #   web_search, web_fetch
│   ├── skill.ts              #   Superpowers skill loading tool
│   ├── worktree.ts           #   Git worktree management
│   ├── background-agent.ts   #   Background agent tool interface
│   ├── review.ts             #   Code review dispatch tool
│   ├── verify.ts             #   Verification check tool
│   └── index.ts              #   Barrel exports & default registry
├── ui/                       # Terminal UI
│   ├── theme.ts              #   Colors, gradients, ASCII banner
│   ├── spinner.ts            #   Loading spinners
│   └── permission-prompt.ts  #   Interactive permission dialog
└── utils/
    ├── config.ts             #   Zod-validated config with env support
    ├── hardware.ts           #   Apple Silicon hardware detection
    ├── backend-detect.ts     #   LLM backend auto-detection
    ├── model-recommender.ts  #   RAM-based model recommendation engine
    └── files.ts              #   Project detection & analysis

Tech Stack

Development

npm run build        # compile TypeScript -> dist/
npm run dev          # run via tsx (no build)
npm start            # run compiled output
npm test             # run tests
npm run test:watch   # tests in watch mode
npm run clean        # remove dist/

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create your branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

Changelog

v2.0.0

• Superpowers skill system — 14 built-in skills (TDD, debugging, code review, worktrees, brainstorming, and more) with support for custom project-local and global skills
• Smart model routing — automatically selects the optimal model (7-70B) per task complexity tier (fast/standard/capable)
• Quality gates — validates agent outputs and catches local LLM failure patterns (false success, hallucinated paths, ignored test failures)
• Reasoning engine — chain-of-thought scaffolding that improves local LLM reasoning by 20-40%
• Code review tool — sub-agent-powered two-stage review (spec compliance + code quality) with severity levels
• Verification gates — evidence-based completion with automated test/build/lint/type-check for Node/Rust/Python/Go
• Background agents — non-blocking parallel agents with status tracking and abort control
• Git worktrees — isolated workspaces for parallel development branches with auto-setup
• Error tracker — detects repeated error patterns and provides targeted correction prompts
• 7 new tools — skill, git_worktree, background_agent, code_review, verify (36 total)
• Input queue — type-ahead while agent generates, prompts queued and processed sequentially
• Auto-init — ua init sets up .ultraagent/ with config, skills, plugins, MCP; auto-runs on first ua chat
• Text-to-ToolCall parser — catches local models (qwen, etc.) that output tool calls as JSON text
• ua verify — CLI command to run project verification checks
• ua router — CLI command to inspect smart model routing status
• MCP client — external tool integration via Model Context Protocol
• Plugin loader — custom tool plugins for extensibility
• Session persistence — session store with auto-save and restore

v1.1.0

• Smart context management — automatically reduces tools and prompt size to fit within model's context window
• Improved output formatting — cleaner responses with structured formatting rules (status icons, tables, tree output)
• 11 new tools — git_merge, git_revert, git_stash, git_cherry_pick, git_rebase, gh_pr, gh_issue, sub_agent_batch, sub_agent_status, plan_create/status/update
• Context overflow detection — clear error message with actionable solutions when context window is too small
• Tool token estimation — dynamic tool binding based on available context budget

v1.0.0

• Initial release with 18 tools, agentic loop, sub-agents, memory, project scanner, auto-setup

License

MIT