User Guide

Get jaato running on your terminal. This guide walks you through installing from TestPyPI, choosing an AI provider, authenticating, and configuring the TUI for daily use.

What You'll Learn

• Installing jaato from TestPyPI (or from source)
• Starting the server and connecting the TUI
• Choosing and authenticating with an AI provider
• Configuring context management (garbage collection)
• Managing sessions, keybindings, and themes
• Keeping jaato up to date

# You'll need Python 3.10+
python3 --version
# Python 3.10.x or higher

# And pip (usually bundled with Python)
pip --version

Installation

jaato is published as three packages on TestPyPI during the alpha period:

• jaato-sdk — lightweight protocol and types
• jaato-server — the daemon that runs AI models and tools
• jaato-tui — the terminal interface you interact with

Install all three in a virtual environment. The --extra-index-url flag tells pip to fetch jaato packages from TestPyPI while resolving other dependencies from the regular PyPI.

# Create a virtual environment
python3 -m venv jaato-env
source jaato-env/bin/activate  # Windows: jaato-env\Scripts\activate

# Install all three packages from TestPyPI
pip install \
  --extra-index-url https://test.pypi.org/simple/ \
  jaato-sdk jaato-server jaato-tui

# Verify the install
jaato --help
jaato-server --help

# Clone the repository
git clone https://github.com/Jaato-framework-and-examples/jaato.git
cd jaato

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install all packages in editable mode
pip install -e jaato-sdk/. \
  -e "jaato-server/.[all]" \
  -e "jaato-tui/.[all]"

First Launch

jaato uses a server-client architecture. The server runs as a background daemon and handles AI model calls, tool execution, and session persistence. The TUI connects to the server over IPC (Unix socket on Linux/macOS, named pipe on Windows).

Initialize your project

Before your first session, run jaato --init in your project directory. This creates a .jaato/ folder with documented example configs for GC, permissions, keybindings, themes, and more. You can skip this step and configure later, but it gives you a head start.

Start the server

Launch the server with --daemon to run it in the background. If you omit --ipc-socket, the server uses a platform-specific default:

• Linux / macOS: /tmp/jaato.sock (Unix domain socket)
• Windows: \\.\pipe\jaato (named pipe)

Connect the TUI

Once the server is running, start the TUI with jaato. It auto-discovers the server via the default socket path. On Windows, use the same command — the client detects the named pipe automatically.

Server management

• jaato-server --status — check if the server is running
• jaato-server --stop — stop the daemon
• jaato-server --restart — restart with the same parameters

# 1. Initialize project config (first time only)
jaato --init

# 2. Set up your .env with provider credentials
cp .env.example .env
# Edit .env with your provider and API key

# Start as background daemon (uses /tmp/jaato.sock)
jaato-server --daemon

# Or specify a custom socket path
jaato-server --ipc-socket /tmp/jaato.sock --daemon

# Start with both local and remote access
jaato-server \
  --ipc-socket /tmp/jaato.sock \
  --web-socket :8080 \
  --daemon

# Check status
jaato-server --status

# MSYS2: same as Linux/macOS (uses \\.\pipe\jaato)
jaato-server --daemon

# cmd.exe / PowerShell: background with start
start /b jaato-server

# Connect to running server (auto-discovers socket/pipe)
jaato

# Or specify socket path explicitly
jaato --connect /tmp/jaato.sock

# The TUI auto-starts the server if not running,
# so in most cases you can just run:
jaato

Choosing a Provider

jaato supports multiple AI providers. Pick the one that fits your needs and budget. You configure your choice in a .env file in your project directory.

Provider	Best For	Cost
Google GenAI	Long context, multimodal, free tier	Free tier / pay-as-you-go
Anthropic	Complex reasoning, code generation	Pay-as-you-go API
GitHub Models	Multi-model access (GPT, Claude, Gemini, Llama)	Free tier for all GitHub users
Ollama	Privacy, no API costs, runs locally	Free (your hardware)
Claude CLI	Claude Pro/Max subscribers	Included in subscription
Antigravity	Gemini 3 and Claude via Google OAuth	Free (Google IDE quota)
Zhipu AI	GLM models, chain-of-thought reasoning	Pay-as-you-go API

Set JAATO_PROVIDER and MODEL_NAME in your .env file. The right-hand panel shows examples for each provider.

JAATO_PROVIDER=google_genai
GOOGLE_GENAI_API_KEY=AIza...your-key
MODEL_NAME=gemini-2.5-flash

JAATO_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-api03-...
MODEL_NAME=claude-sonnet-4-20250514

JAATO_PROVIDER=github_models
GITHUB_TOKEN=github_pat_...
MODEL_NAME=openai/gpt-4o

JAATO_PROVIDER=ollama
MODEL_NAME=qwen3:32b
# Requires: ollama serve && ollama pull qwen3:32b

Authentication

Some providers use simple API keys (set in .env), while others offer interactive OAuth flows you run from the TUI.

API Key Providers

For Google GenAI, Anthropic, GitHub Models, and Zhipu AI, set the appropriate key in your .env file. No additional auth step is required.

OAuth Providers

Antigravity, Anthropic (subscription), and GitHub (device code) support browser-based OAuth login. Run the auth command in the TUI:

• anthropic-auth login — Anthropic OAuth (PKCE)
• github-auth login — GitHub device code flow
• antigravity-auth login — Google OAuth
• zhipuai-auth login — Zhipu AI API key entry

Tokens are stored in ~/.config/jaato/ and persist across sessions. Use *-auth status to check your current authentication state.

Claude CLI Provider

The Claude CLI provider delegates authentication to the Claude Code CLI. Install and log in to the CLI separately:

# Antigravity (opens browser for Google sign-in)
antigravity-auth login

# Check status
antigravity-auth status

# Add multiple accounts for load balancing
antigravity-auth login    # run again for each account
antigravity-auth accounts # list all accounts

# Start device code flow
github-auth login
# Opens browser with a code to enter

# Poll for completion (if needed)
github-auth poll

# Check status
github-auth status

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Log in (uses your Claude Pro/Max subscription)
claude login

# Then in your .env:
# JAATO_PROVIDER=claude_cli
# MODEL_NAME=sonnet

Configuration

jaato reads configuration from a .env file in your workspace directory and from several JSON config files under .jaato/.

Initialize project configuration

Run jaato --init to scaffold a .jaato/ directory with documented example files for every configuration option. This gives you a ready-to-edit starting point with GC settings, permissions, keybindings, themes, subagent profiles, prompt templates, and more.

Configuration files

File	Purpose
.env	Provider, model, credentials, rate limits
.jaato/gc.json	Garbage collection strategy and thresholds
.jaato/permissions.json	Tool permission whitelist/blacklist rules
.jaato/sandbox.json	Filesystem access boundaries
.jaato/keybindings.json	Custom keybindings (project-level)
.jaato/reliability-policies.json	Loop prevention and pattern detection
.jaato/profiles/	Subagent profile definitions
.jaato/themes/	Custom and override themes
.jaato/prompts/	Reusable prompt templates
.jaato/instructions/	System instructions (markdown)
.jaato/references/	Reference sources for agent context
.mcp.json	MCP server configuration

User-level config

Files in ~/.jaato/ apply across all projects:

• ~/.jaato/keybindings.json — global keybindings
• ~/.jaato/theme.json — custom theme
• ~/.jaato/preferences.json — saved preferences (theme, format)
• ~/.jaato/sandbox_paths.json — global filesystem boundaries

# Scaffold .jaato/ with all example configs
jaato --init

# What you get:
# .jaato/
# ├── gc.json                   GC / context budget
# ├── permissions.json          Tool access policies
# ├── sandbox.json              Filesystem boundaries
# ├── keybindings.json          Keyboard shortcuts
# ├── reliability-policies.json Loop prevention
# ├── keybindings/              Terminal-specific profiles
# │   ├── vscode.json
# │   └── tmux.json
# ├── themes/                   All 6 built-in themes + custom starter
# ├── profiles/                 Subagent profiles
# ├── instructions/             System instructions (markdown)
# ├── prompts/                  Prompt templates
# └── references/               Reference sources

# The two required variables
JAATO_PROVIDER=google_genai
MODEL_NAME=gemini-2.5-flash

# Authentication (provider-specific)
GOOGLE_GENAI_API_KEY=AIza...your-key

# Rate limiting (prevents 429 errors)
AI_REQUEST_INTERVAL=0.5

# Parallel tool execution (default: true)
JAATO_PARALLEL_TOOLS=true

# Deferred tool loading (default: true)
JAATO_DEFERRED_TOOLS=true

# Per-session logs
JAATO_SESSION_LOG_DIR=.jaato/logs

{
  "mcpServers": {
    "Atlassian": {
      "type": "stdio",
      "command": "mcp-atlassian"
    },
    "GitHub": {
      "type": "stdio",
      "command": "mcp-github"
    }
  }
}

Context Management (GC)

AI models have a limited context window. When a conversation grows too long, jaato automatically triggers garbage collection to free up space while preserving recent context.

GC strategies

Strategy	Behavior
truncate	Remove oldest conversation turns
summarize	Compress old turns into summaries
hybrid	Summarize middle turns, truncate ancient ones, keep recent
budget	Token budget-based cleanup

Key thresholds

• Threshold (default 80%) — GC triggers when context reaches this % of the window
• Target (default 60%) — GC aims to reduce usage to this %
• Pressure (default 90%) — at this %, even "preservable" entries get evicted

GC can be configured via environment variables or a JSON file.

# Trigger GC at 80% context usage (default)
JAATO_GC_THRESHOLD=80.0

# Target 60% usage after cleanup (default)
JAATO_GC_TARGET=60.0

# Start evicting preservable entries at 90% (default)
JAATO_GC_PRESSURE=90.0

{
  "type": "hybrid",
  "threshold_percent": 80.0,
  "target_percent": 60.0,
  "pressure_percent": 90.0,
  "preserve_recent_turns": 5,
  "summarize_middle_turns": 10,
  "notify_on_gc": true
}

# Set pressure to 0 for continuous GC
# (runs every turn regardless of usage)
JAATO_GC_PRESSURE=0

Session Management

jaato persists conversations to disk so you can resume them later. Sessions are managed via TUI commands.

TUI commands

• session list — list all saved sessions
• session new [name] — start a new named session
• session attach <id> — resume a previous session
• session delete <id> — permanently remove a session
• reset — clear current conversation history
• model <name> — switch to a different model mid-session

Tool management

• tools list — show all tools and their status
• tools enable <name|all> — enable a tool or all tools
• tools disable <name|all> — disable a tool

Permissions

When the model wants to execute a tool, jaato asks for permission. Responses:

• y — yes, this time
• n — no
• a — always allow this tool
• t — allow for this turn only
• i — allow until session goes idle

# List your sessions
session list

# Create a named session
session new refactoring-auth

# Later, resume it
session attach refactoring-auth

# Switch model on the fly
model gemini-2.5-pro

# Clear history and start fresh
reset

# Show current permission rules
permissions show

# Whitelist a tool permanently
permissions whitelist cli

# Check permission status
permissions status

Keybindings & Themes

Default keybindings

Key	Action
Enter	Submit prompt
Ctrl+C	Cancel current operation
Ctrl+D	Exit
Ctrl+P	Toggle plan display
Ctrl+T	Toggle tool display
Ctrl+G	Open prompt in external editor
Ctrl+F	Search session output
Ctrl+Y	Copy (yank) output to clipboard

Custom keybindings

Override keybindings in .jaato/keybindings.json (project) or ~/.jaato/keybindings.json (global). Key syntax follows prompt_toolkit conventions.

Themes

Six built-in themes: dark (default), light, high-contrast, dracula, latte, and mocha. Switch at any time with /theme.

Create a custom theme by placing a theme.json in .jaato/ or ~/.jaato/. Running jaato --init gives you all built-in themes plus a custom-example.json starter in .jaato/themes/.

{
  "submit": "enter",
  "cancel": "c-c",
  "exit": "c-d",
  "toggle_plan": "c-p",
  "toggle_tools": "c-t",
  "open_editor": "c-g",
  "search": "c-f"
}

# Switch theme in the TUI
/theme dark
/theme light
/theme high-contrast
/theme reload   # reload custom theme.json

{
  "colors": {
    "primary": "#635bff",
    "secondary": "#8b84ff",
    "success": "#10b981",
    "warning": "#f59e0b",
    "error": "#ef4444",
    "muted": "#6b7280",
    "background": "#0f172a",
    "surface": "#1e293b",
    "text": "#f8fafc",
    "text_muted": "#94a3b8"
  }
}

Updating jaato

Upgrade to the latest version by re-running pip with the --upgrade flag.

From TestPyPI

Use the same --extra-index-url flag as the initial install.

From source

Pull the latest code and reinstall in editable mode.

After updating

• Stop the running server: jaato-server --stop
• Start a fresh server: jaato-server --ipc-socket /tmp/jaato.sock --daemon
• Reconnect the TUI: jaato

# Activate your environment
source jaato-env/bin/activate

# Upgrade all three packages
pip install --upgrade \
  --extra-index-url https://test.pypi.org/simple/ \
  jaato-sdk jaato-server jaato-tui

# Restart the server
jaato-server --stop
jaato-server --ipc-socket /tmp/jaato.sock --daemon

# Pull latest changes
cd jaato
git pull

# Reinstall
source .venv/bin/activate
pip install -e jaato-sdk/. \
  -e "jaato-server/.[all]" \
  -e "jaato-tui/.[all]"

# Restart server
jaato-server --stop
jaato-server --ipc-socket /tmp/jaato.sock --daemon