< Back

Documentation v3.2.6

Getting started with taracode v3.2.6 - your open source DevOps & Cloud SI Assistant. SI, super intelligence, is the new name for AI.

Highlights

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

Investigate & Operate

Investigate mode is read-only and never prompts. Switch to operate and every mutation is gated by the policy before it runs.

/mode operate Unlock every tool
/mode Show the current mode

Policy Engine

Protected targets, deny patterns and required dry runs decide every mutation, before a remembered permission or a prompt does.

/policy show Effective policy and source
/permissions Manage remembered rules

Audit Log

Every mutation is recorded before it runs, allowed or denied, with the rule that decided it.

/audit Recent mutations
/audit export json Export the log

Project Memory

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

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

Model Scoreboard

33 offline DevOps tasks replayed against every model in the registry, with the product's own loop, policy gate and redaction. Published on the evals page.

taracode eval run Score a model
taracode eval report Rebuild the board

Context Management

Intelligent context window management for local LLMs. Auto-truncates tool output, compacts conversations, and tracks usage.

/compact Free context space
/stats Session statistics

Model Selection

Switch between Ollama models on the fly. Choose the right model for each task - from fast lightweight models to powerful reasoning engines.

/model List available models
/model glm-4.7-flash Switch to model

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 cask
$ brew install --cask tara-vision/taracode/taracode
Upgrading from the formula? The Homebrew formula was retired with v2.1.0. Run brew uninstall taracode once, then the cask command above.
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, mode, policy and tools.

Command Description
/init Initialize the project (creates TARACODE.md and .taracode/)
/reload Reload project context from TARACODE.md
/status Show project and session status
/session [new [name]|load <id>|delete <id>|rename <id> <name>] Show or manage the current session
/sessions List all sessions
/clear Clear the conversation (new session)
/model Switch between available models
/think [auto|off|on|low|medium|high] Show or set the reasoning mode
/mode [investigate|operate] Show or switch the operating mode
/permissions [allow|deny|ask <tool|all>|reset] Remembered answers for mutations
/audit [all|export json|clear] Mutations recorded in this project
/policy show Effective policy and where it comes from
/plan Show the active plan
/context Context window budget breakdown
/compact Force conversation compaction
/stats Session statistics
/usage Token usage for this session
/history [n|all] File operation history
/undo [n|--dry-run] Undo file modifications
/diff [export] Show or export session changes
/remember <text> [#tag] Save a memory about this project
/memory [search <q>|delete <id>|export|import <file>|stats|cleanup|clear] Project memories
/mcp [connect|disconnect <name>|tools] MCP servers and their tools
/tools List available tools
/upgrade [check|now|skip|changelog|status] Check for and install updates
/doctor Diagnose the LLM server and tools
/help Show this help
cd <dir> / cd .. / cd Navigate within the project (sandboxed)
pwd Show the current directory
@file Reference a file in a prompt (Tab completes)
exit / quit Exit with a session summary

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]

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 (vision models such as Gemma 4)
> What's in this diagram? @architecture.png
Tab Completion: Press Tab after typing @ for fuzzy file matching. The autocomplete respects your .gitignore patterns.
No /init required: Reading a file or an image off disk needs no .taracode/, so @ references and Tab completion work whether or not the project has been initialised.

Web Tools

Two of the fifteen tools reach the internet: web_search and web_fetch. Both are always a read; --offline hides them both, along with the startup update check.

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.

web_fetch Safety

web_fetch downloads a public http or https URL and returns its readable text, tags stripped. It resolves the host itself and refuses loopback, private (RFC 1918 and ULA) and link-local addresses (including the cloud metadata address), carrier-grade NAT, multicast and unspecified addresses, then dials the checked address directly - so a DNS answer cannot change between the check and the connection. Every redirect hop (up to five) is checked the same way.

Offline: --offline disables web_search, web_fetch and the startup update check. It does not reach into shell: curl, wget -O-, dig, nslookup, host and ping still count as reads there.

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 LLM applications to external data sources and tools. taracode acts as an MCP client, allowing you to connect to any MCP-compatible server.

Read, Mutate and Permission

An MCP tool joins the same registry as the fifteen built-in tools. A server that annotates a tool readOnlyHint: true gets a read form and is exposed in investigate mode; every other MCP tool is a mutation and stays hidden until you switch to operate mode. MCP tools skip the protected-target, deny-pattern and required-dry-run checks that gate the built-in tools - they are gated by the remembered per-tool permission (or a prompt) only.

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 taracode 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 works with any Ollama model that carries the tools capability. Pick the tier that fits your machine; the table lists the models we test against as of September 2026.

Recommended models by RAM

Model Download Machine Notes
gemma4:12b ~8 GB 16 GB Tools, thinking and vision; the laptop default
glm-4.7-flash ~19 GB 32 GB Recommended - top of the taracode scoreboard (97% of the eval tasks passed); a 30B mixture-of-experts model with 3B active parameters; needs Ollama 0.14.3 or newer
qwen3.8:27b ~18 GB 32 GB strongest agentic results in its class on public benchmarks; needs Ollama 0.32.12 or newer
qwen3.6:35b ~23 GB 48 GB and up Fast mixture-of-experts model with a 256K context

Which of these actually solve DevOps tasks is measured, not guessed: see the model scoreboard, refreshed with every release.

Terminal
# 16 GB machines
$ ollama pull gemma4:12b

# 32 GB machines
$ ollama pull glm-4.7-flash

# 48 GB and up
$ ollama pull qwen3.6:35b
Context window: Ollama defaults to a 4,096-token context on machines with less than 24 GB of GPU memory, which is too small for taracode's tool schemas. Start Ollama with OLLAMA_CONTEXT_LENGTH=32768 (or raise Context length in the Ollama app settings). taracode warns you after the first reply when the server's window is too small, and /context shows it.
Vision: Gemma 4 and Qwen 3 models accept images. Reference a screenshot with @screenshot.png to analyze UI mockups, architecture diagrams, and more.
Native Ollama API: taracode talks to Ollama over its native API instead of an OpenAI-compatible shim: it requests the context window itself through context.window (default auto = 32,768 tokens, or the model's native maximum when smaller, so OLLAMA_CONTEXT_LENGTH is no longer needed for Ollama), and sends the reasoning mode (think: auto by default) with every request, downgraded to auto automatically on a model without the thinking capability. Tool calling is native only, with no fallback: a model whose /api/show doesn't report the tools capability is refused at startup or on /model (Ollama only - vLLM and llama.cpp have no capability endpoint, so their tool calls go out for the server to accept or reject). taracode also ships an embedded model registry with a recommendation per RAM tier - 16 GB gemma4:12b, 32 GB glm-4.7-flash, 48 GB and up qwen3.6:35b, plus a small gemma4:e4b tier for helper roles and quick checks. Run taracode doctor (or /doctor in a session) to see the server, your installed models with their capabilities and registry membership, your machine's RAM tier and the registry's recommendation, the Ollama version gate, and the external tools on PATH.

Modes and Policy

taracode starts in investigate mode: read-only, and it never prompts you. Switch to operate mode to unlock every tool - from there, every mutation passes through the policy before it runs.

Investigate Mode (default)

Only the tools with a read form are exposed - thirteen of the fifteen, eleven with --offline - and nothing is ever written or asked. An MCP tool joins the read set only when its server marks it readOnlyHint: true; every other MCP tool is a mutation and stays hidden.

Operate Mode

Every tool is exposed - thirteen of the fifteen with --offline, since web_search and web_fetch stay hidden in both modes. Every mutation passes through the same gate, in order: classify (read or mutate, from the call's arguments, not its name), policy (protected targets and deny patterns), audit (the decision is recorded before the call runs), dry run (when the tool requires one), permission (the remembered rule, or a prompt), preview (edit_file shows its diff), then execute. MCP tools skip the protected-target and deny-pattern checks; they are gated by permission only.

taracode REPL
# Show the current mode
> /mode

# Switch to operate mode
> /mode operate

# Or start in operate mode
$ taracode --mode operate

Protected Targets and Deny Patterns

Protected targets are a hard deny in operate mode, with the reason printed: kube contexts, namespaces, cloud accounts, paths and hosts named in the policy. A kubectl or helm mutation run through shell carries its context and namespace like the dedicated tools, also inside loops, conditionals and subshells; a mutation of every namespace, of several contexts, or of one taracode cannot determine before it runs counts as touching the protected ones. Deny patterns are command globs refused outright. kubectl apply shows a server-side diff first, terraform apply requires a plan produced in this session and shows its summary, and helm upgrade runs --dry-run first - a release with a --post-renderer is refused, since the dry run would run the renderer before you approve.

Policy Files

.taracode/policy.yaml merges over ~/.taracode/policy.yaml (lists unioned, booleans take the stricter value); with neither file, taracode uses a built-in policy identical to the one below. /init writes this starter:

.taracode/policy.yaml
# taracode policy (see: taracode doctor, /policy show).
# The model never sees this file. .taracode/policy.yaml merges over ~/.taracode/policy.yaml:
# lists are unioned and booleans take the stricter value. With no policy file at all, taracode
# uses a built-in policy identical to this one. Patterns are globs (* ? and ** in paths).
version: 1
mode: investigate               # the mode a session starts in: investigate or operate
protected:                      # never mutated in operate mode (hard deny, printed reason)
  kube_contexts: ["*prod*", "*production*"]
  kube_namespaces: ["kube-system"]
  cloud_accounts: []            # AWS account ids, Azure subscription ids, GCP project ids, or *globs*
  paths: ["**/*.tfstate", ".git/**"]
  hosts: []
deny:                           # refused outright; the last pattern keeps the policy files safe
  commands: ["rm -rf /*", "kubectl delete namespace *", "terraform destroy*", "*.taracode/policy.yaml*"]
require_dry_run:                # shown before the permission prompt
  kubectl_apply: true           # kubectl diff first
  terraform_apply: true         # a plan from this session, its summary first
  helm_upgrade: true            # helm --dry-run first (upgrade and install)
redact:
  enabled: true                 # secrets in tool output become [redacted:<kind>]
  extra_patterns: []            # additional Go regular expressions
Broken policy: a policy file that fails to parse locks the session to investigate mode until it is fixed; /mode operate and /policy show report the parse error, and taracode doctor reports the policy status.

Inspecting and Managing

/policy show prints the effective policy and where it comes from. /permissions manages the remembered per-tool rules - reads never ask, and the default for a mutation is ask. Every mutation, allowed or denied, is appended to .taracode/audit.jsonl before it runs.

taracode REPL
# Effective policy and its source
> /policy show

# Remembered per-tool rules
> /permissions
> /permissions allow kubectl
> /permissions reset

# This session's mutations, every session, or export/clear
> /audit
> /audit all
> /audit export json
> /audit clear

Configuration

Config File

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

~/.taracode/config.yaml
# The Ollama host (required; --host and TARACODE_HOST override it)
host: http://localhost:11434

# Model name (optional; auto-detected from the server when unset)
# model: glm-4.7-flash

# Generation options for the main chat
generation:
  temperature: 0.7      # sampling randomness, 0.0-2.0
  top_p: 0.9             # nucleus sampling threshold, 0.0-1.0
  num_predict: 0          # max tokens per response, 0 = model default

# Context management
context:
  max_tool_output_lines: 500
  max_tool_output_chars: 15000
  max_tool_iterations: 20
  compaction_enabled: true
  compaction_threshold: 0.75
  compaction_keep_recent: 4
  window: auto           # "auto" (the model's native max, capped) or a token count

# Reasoning mode sent with every request: auto, off, on, low, medium, high
# Change it mid-session with /think without restarting taracode
think: auto

# How long Ollama keeps the model loaded ("" = server default, "-1" = keep loaded)
keep_alive: ""

# Starting operating mode: investigate or operate (unset starts in investigate,
# or the mode a policy file names - see .taracode/policy.yaml)
mode: investigate

# Disable every internet-facing tool (web_search, web_fetch) and the startup update check
offline: false

# Security scanning
scan:
  default_severity: ""   # e.g. "HIGH,CRITICAL"

# Web search
search:
  primary: duckduckgo    # brave, duckduckgo, or searxng
  fallback: searxng
  brave_api_key: ""      # optional: becomes the default primary when set

# Persistent project knowledge
memory:
  enabled: true
  max_memories: 500
  max_context_tokens: 2000
  retention_days: 90
  auto_capture: true

# Auto-update
upgrade:
  auto_check: true        # check for updates on startup
  auto_upgrade: false
  show_changelog: true

# Model Context Protocol servers (see the MCP section)
mcp:
  enabled: true
  servers: []

# Show a diff preview before applying edit_file operations
preview_edits: true
preview_threshold: 0

# Show token usage in the prompt, like [5.0k/32k]
show_context_budget: true
max_context_tokens: 32768

# Disable live streaming of shell command output to the terminal
no_stream_commands: false

See config.example.yaml for every option, including MCP server examples.

Migrating from 2.x or 3.0.0-alpha.1: rename the model: section to generation: and set model: <name> at the top level; rename security.default_severity to scan.default_severity; delete agents: and watch: (no longer read). A 2.x config file still starts taracode - each of these prints a one-time migration warning after the startup banner.

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., glm-4.7-flash)
--mode Operating mode (investigate, operate)
--offline Disable every internet tool (web_search, web_fetch) and the update check
--severity Default severity filter for security scans
--no-stream Disable streaming output
--no-spinner Disable spinner animations
--max-tool-output <lines> Max lines per tool output (0 = unlimited)
--max-iterations <n> Max consecutive tool calls per message
--no-compaction Disable automatic conversation compaction