Back

Documentation

Getting started with taracode v1.0.0 - your open source DevOps & Cloud AI Assistant

Highlights

The most powerful features that set taracode apart from other DevOps assistants.

Screen Monitoring

Let the AI watch your screen and catch errors before you do. Perfect for monitoring builds, deployments, and dashboards.

/watch this Analyze screens now
/watch start Continuous monitoring

Multi-Agent System

7 specialized agents collaborate on complex tasks: Planner, Coder, Tester, Reviewer, DevOps, Security, and Diagnostics.

/agent list View all agents
/agent use security Route to agent

Autonomous Tasks

Plan and execute multi-step tasks with checkpoints and rollback. Built-in templates for Docker, Kubernetes, Terraform, and Git workflows.

/task "Add auth" Create task
/task rollback Safe rollback

Project Memory

Persistent knowledge across sessions. The AI remembers your project conventions, decisions, and patterns without re-explaining.

/remember "..." Save knowledge
/memory search Find memories

Getting Started

Installation

Install taracode using the quick install script, Homebrew, or Go.

Terminal - Quick Install (Recommended)
# One-line installer
$ curl -fsSL https://code.tara.vision/install.sh | bash
Terminal - Homebrew (macOS / Linux)
# Install via Homebrew
$ brew tap tara-vision/taracode
$ brew install taracode
Terminal - Go Install
# Install with Go (requires Go 1.23+)
$ go install github.com/tara-vision/taracode@latest

Project Initialization

Initialize taracode in your project directory to enable all features.

Terminal
$ cd /path/to/your/project
$ taracode

# Inside the REPL, initialize the project
> /init

Project initialized. @ file references and permissions enabled.

REPL Commands

Use these commands within the taracode REPL to manage your session and tools.

Command Description
/help Show help and available commands
/init Initialize project context (required before use)
/model Switch between available Ollama models
/mode Switch operating mode (devops/security)
/session new ["name"] Create a new named session
/session load <id> Load a previous session (supports partial IDs)
/session delete <id> Delete a session with confirmation
/session rename <id> <name> Rename a session
/sessions List all saved sessions with summaries
/permissions View and manage tool permissions
/audit View security audit log
/tools List all 58 built-in AI tools + MCP tools
/mcp List configured MCP servers and status
/mcp connect <name> Connect to an MCP server
/mcp disconnect <name> Disconnect from an MCP server
/mcp tools List tools from connected MCP servers
/agent Show Multi-Agent System overview
/agent list List all 7 specialized agents with status
/agent status <type> Show detailed status for an agent
/agent config example Show example agent configuration
/agent use <type> Route next prompt to specific agent
/context --agents Show per-agent context usage
/usage Show token usage statistics
/history Show file operation history
/history <n> Show last n operations
/undo Undo last file modification
/undo --dry-run Preview what would be undone
/context Show LLM context window contents
/watch this Capture and analyze screens now
/watch start Start continuous screen monitoring
/watch stop Stop screen monitoring
/watch status Show monitoring state
/remember <text> Save a project memory
/memory List all project memories
/memory search <query> Search memories by content
/memory delete <id> Delete a memory (supports partial ID)
/memory export [file] Export memories to JSON
/memory import <file> Import memories from file
/memory stats Show memory statistics
/memory cleanup [days] Remove old unused memories
/task List all tasks and their status
/task new <name> Create a new autonomous task
/task run <id> Run or resume a task
/task status <id> Show task execution status
/task rollback <id> Rollback a task to a checkpoint
/task template List or apply task templates
/diff Show all file changes made this session
cd <dir> Navigate within project (sandboxed)
pwd Show current directory
exit Exit taracode

Project Memory

Save and recall project-specific knowledge across sessions. Memories are automatically injected into the LLM context.

Saving Memories

Use /remember to save project knowledge. Add hashtags for organization.

taracode REPL
# Save a decision
> /remember We use PostgreSQL for production databases

# Save with tags
> /remember Always use snake_case for variables #style

# List all memories
> /memory

Memory Categories

Memories are automatically categorized based on content:

Category Icon Examples
Decision 🏛️ "We decided...", "Architecture uses..."
Pattern 📐 "Always use...", "Convention is..."
Error 🐛 "Error caused by...", "Bug fix for..."
Learning 💡 General project observations

Managing Memories

taracode REPL
# Search memories
> /memory search database

# Delete by ID (partial match works)
> /memory delete abc12

# Export for backup
> /memory export memories.json

# Import memories
> /memory import memories.json

# View statistics
> /memory stats

# Cleanup old unused memories
> /memory cleanup 30
Context Injection: Relevant memories are automatically loaded into the LLM context based on recency and usage frequency. Use /context to see how many memories are loaded.

Auto-Capture

taracode can detect memory-worthy statements and offer to save them. This triggers when you state conventions or make corrections.

taracode REPL
> No, we always use camelCase in this project

💡 Remember: "Use camelCase in this project"? [y/N]

Autonomous Task Execution

Define multi-step tasks that execute autonomously with checkpoints and rollback support.

Creating Tasks

Tasks are defined with steps that execute in sequence. Each step creates a checkpoint for safe rollback.

taracode REPL
# Create a new task
> /task new "Add authentication middleware"

# List all tasks
> /task

# Run a task
> /task run abc123

# Check task status
> /task status abc123

Checkpoints and Rollback

Every step creates an automatic checkpoint. If something goes wrong, you can rollback to any previous checkpoint.

taracode REPL
# Rollback to a specific checkpoint
> /task rollback abc123 2

# Rollback to previous step
> /task rollback abc123

Task Templates

Use pre-defined templates for common DevOps workflows. Templates are YAML files with variable substitution.

taracode REPL
# List available templates
> /task template

# Apply a template
> /task template k8s-deploy --app myapp --ns production
Dry Run Mode: Many tools support a dry_run parameter to preview changes without executing them. Task steps can also be run in dry-run mode to validate before execution.

Session Changes

View all file modifications made during your session with the /diff command.

taracode REPL
# Show all changes in current session
> /diff

Modified files:
  M main.go (+15, -3)
  A config/auth.yaml
  D old_config.json

File References

Reference files and directories in your prompts using the @ prefix.

taracode REPL
# Reference a single file
> Review @main.go and suggest improvements

# Reference multiple files
> Compare @old.go with @new.go

# Reference a directory
> Explain the code in @internal/tools/

# Reference an image (Gemma3 vision)
> What's in this diagram? @architecture.png
Tab Completion: Press Tab after typing @ for fuzzy file matching. The autocomplete respects your .gitignore patterns.

Web Tools

taracode includes privacy-focused web tools for searching and fetching content.

taracode REPL
# Search the web (DuckDuckGo with SearXNG fallback)
> Search for best practices for Terraform modules

# Fetch content from a URL
> Summarize this article: https://example.com/guide
Privacy First: Web search uses DuckDuckGo by default (no API key required). If DuckDuckGo is unavailable, it automatically falls back to SearXNG and notifies you.
Premium Search: For enhanced results, configure a Brave Search API key. Set brave_api_key in your config file to use Brave as your primary search provider.

MCP (Model Context Protocol)

Connect to external MCP servers to extend taracode with additional tools like GitHub, PostgreSQL, Slack, and more.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external data sources and tools. taracode acts as an MCP client, allowing you to connect to any MCP-compatible server.

Configuration

Configure MCP servers in your ~/.taracode/config.yaml file.

~/.taracode/config.yaml
# MCP (Model Context Protocol) servers
mcp:
  enabled: true
  servers:
    - name: github
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"
      auto_connect: false
      timeout: 30s

Usage

taracode REPL
# List configured MCP servers
> /mcp

# Connect to a server
> /mcp connect github
Connected to github (5 tools discovered)

# List tools from connected servers
> /mcp tools

# Now you can ask the AI to use MCP tools
> List my GitHub repositories
Environment Variables: Use ${VAR_NAME} syntax in your config for secrets. taracode automatically expands environment variables when connecting to MCP servers.

Popular MCP Servers

Server Description
@modelcontextprotocol/server-github GitHub repositories, issues, PRs, and more
@modelcontextprotocol/server-postgres PostgreSQL database queries
@modelcontextprotocol/server-slack Slack channels and messages
@modelcontextprotocol/server-filesystem Extended filesystem operations
@modelcontextprotocol/server-brave-search Brave Search API integration

Model Support

taracode is optimized for Gemma3 models running locally via Ollama.

Gemma3 (Recommended)

Gemma3 provides the best balance of tool execution, vision capabilities, and action-oriented behavior.

Model Size RAM Required Use Case
gemma3:12b 12B ~12GB Limited hardware, basic tasks
gemma3:27b 27B ~28GB Recommended - Best overall performance
Terminal
# Pull the recommended model
$ ollama pull gemma3:27b

# Or for limited hardware
$ ollama pull gemma3:12b
Vision Support: Gemma3 models support image analysis. Reference images with @screenshot.png to analyze UI mockups, architecture diagrams, and more.

Multi-Agent System

taracode introduced a multi-agent architecture with 7 specialized agents for different tasks.

Available Agents

Agent Specialization
planner Task decomposition and dependency analysis
coder Code generation and editing
tester Test execution and output analysis
reviewer Code review and quality checks
devops Infrastructure and deployment operations
security Security scanning and vulnerability analysis
diagnostics Failure analysis and root cause detection

Agent Routing

Agents are automatically selected based on your prompt content. You can also manually route to a specific agent.

taracode REPL
# View all agents
> /agent list

# Check agent status
> /agent status planner

# Route to specific agent
> /agent use security
> Scan this project for vulnerabilities

Agent Configuration

Customize agent behavior globally or per-project. Each agent can have its own model, temperature, and timeout.

.taracode/agents.yaml
# Per-project agent overrides
planner:
  model: gemma3:12b
  temperature: 0.3

coder:
  model: gemma3:27b
  temperature: 0.4
  timeout: 300
Verbose Errors: Use --verbose-errors flag for detailed failure analysis with root cause detection and actionable suggestions.

Screen Monitoring

taracode v0.4.5 introduces AI-powered screen monitoring that captures and analyzes your screen for errors, warnings, and improvement opportunities. Currently available on macOS.

Watch Commands

Command Description
/watch this Capture and analyze all screens now (one-time)
/watch start Start continuous screen monitoring
/watch stop Stop monitoring
/watch status Show current monitoring state
Requirements: Screen Recording permission must be granted in System Preferences > Privacy & Security > Screen Recording.

How It Works

The watch feature uses perceptual hashing to detect significant screen changes (15% threshold by default), then sends screenshots to the vision model for analysis. In continuous mode, it monitors at 2-second intervals with rate limiting (max 6 analyses per minute).

Detection Categories

  • [ERROR] - Error messages, stack traces, failed commands
  • [WARNING] - Yellow/orange alerts, deprecation notices
  • [IMPROVEMENT] - Inefficient patterns, security issues, suggestions

Operating Modes

DevOps Mode (Default)

The default mode with access to 58 built-in DevOps tools plus MCP integrations for Kubernetes, Terraform, Docker, and multi-cloud operations.

Security Mode

Enhanced mode with audit-first enforcement and security scanning tools.

Security Mode features:
  • Audit-first enforcement - all write/execute operations require confirmation
  • Batch confirmation - allow/deny all remaining operations at once
  • Security scanning tools (Trivy, Gitleaks, tfsec, kubesec, SAST)
  • Audit log with JSON/HTML export via /audit
  • Severity filtering with --severity flag
Terminal
# Start in security mode
$ taracode --mode security

# Or switch modes during a session
> /mode security

# Filter by severity (critical, high, medium, low)
$ taracode --mode security --severity high

# Export audit log
> /audit export json

Configuration

Config File

Create a configuration file at ~/.taracode/config.yaml for persistent settings.

~/.taracode/config.yaml
# Ollama server URL
host: http://localhost:11434

# Default model
model: gemma3:27b

# Context budget display [5.0k/32k]
show_context_budget: true
max_context_tokens: 32768

# Edit preview mode (show diff before applying)
preview_edits: true
preview_threshold: 0
create_backups: true

# Command streaming (real-time output)
stream_commands: true

# Search configuration
search:
  primary: duckduckgo   # or brave
  fallback: searxng
  brave_api_key: ""    # optional

# Project memory settings
memory:
  enabled: true
  max_memories: 500
  max_context_tokens: 2000
  retention_days: 90
  auto_capture: true

# MCP servers (see MCP section for full config)
mcp:
  enabled: true
  servers: []

Environment Variables

Variable Description
TARACODE_HOST Ollama server URL (default: http://localhost:11434)

CLI Flags

Flag Description
--host Ollama server URL
--model Model name (e.g., gemma3:27b)
--mode Operating mode (devops, security)
--severity Default severity filter for security scans
--no-stream Disable streaming output
--no-spinner Disable spinner animations