Juno Agent Documentation

Complete guide to using Juno Agent - the revolutionary external context system that keeps AI tools updated with your exact dependencies.

View on GitHub

Getting Started

Installation

Install Juno Agent

# Install Juno Agent
pip install juno-agent

# Verify installation
juno-agent version

First-time Setup

Basic Setup Commands

# Universal AI tool setup
juno-agent setup

# Start Juno Agent with default model
juno-agent

# Start in debug mode
juno-agent --debug --trace

Setup Wizard Steps

  1. API Key Setup - Secure entry with provider detection
  2. Editor Selection - Integration with popular editors
  3. Model Configuration - Provider and model selection
  4. Project Scanning - Automatic dependency detection
  5. MCP Server Setup - External context configuration

Quick Start Examples

Basic Usage

$ juno-agent
Welcome to JUNO AI CLI
💬 Ready to chat...

In Debug Mode

$ juno-agent --debug
Debug mode enabled
📊 Detailed logging active

External Context System

What is External Context?

Problem Solved

AI tools fail because they don't know your exact dependency versions

Solution

Automatic documentation fetching for your exact dependency versions

Result

AI knows your exact React 18.3.1, not generic React knowledge

Automatic Documentation Setup

External Context Configuration

# Universal AI Tool Configuration System
juno-agent setup

# Configures 26+ AI tools automatically:
✓ Cursor - .cursor/rules/*.mdc created
✓ Claude Code - configured  
✓ Windsurf - .windsurfrules created
✓ VS Code - settings.json updated
✓ GitHub Copilot - configured
✓ + 21 more tools

# Version-specific documentation fetching:
cd my-react-app
juno-agent
# Detects: React 18.3.1, TypeScript 5.4.5
# Fetches current docs for exact versions
# Creates external_context/ symlinks
# All AI tools now have accurate context

Key Benefits

Version-Specific Knowledge

  • • React 18.3.1 specific features and APIs
  • • TypeScript 5.4.5 latest syntax
  • • Framework-specific best practices
  • • Current dependency documentation

One Setup, All Tools

  • • Configures Claude Code automatically
  • • Works with Cursor and Copilot
  • • Supports 20+ AI coding tools
  • • Consistent context everywhere

Model Support

Supported Providers

OpenAI + Open Source

GPT-5, O3/O4, GPT-4.1 Code + Llama 3.3, DeepSeek R1

No Lock-in

Anthropic + Local

Claude-4, Opus 4.1, Sonnet 4 + Ollama models

Privacy-First

Google + Free Tier

Gemini 2.5 Pro/Flash + OpenRouter free models

Cost-Effective

Any LiteLLM Model

xAI Grok 4, Groq, Custom endpoints

Complete Freedom

Interactive Model Selection

TUI Model Browser

┌─ JUNO AI CLI ─────────────────────────────────────────────────────────┐ │ 🤖 Model: GPT-5 (OpenAI) | 💰 Cost: $0.0023 | 🔄 Context: 47.2K │ ├───────────────────────────────────────────────────────────────────────┤ │ Project: my-react-app (React 18.3.1, TypeScript 5.4.5) │ │ Git: main branch ✓ clean | Dependencies: ✓ up-to-date │ └───────────────────────────────────────────────────────────────────────┘ 💬 Chat with AI about your code... > /model ┌─ Available Models ────────────────────────────────────────────────────┐ │ 🟢 GPT-5 (OpenAI) - Latest & Best - 128K context 👁️ 🔧 │ │ 🟢 Claude-4 (Anthropic) - Advanced reasoning - 200K context 👁️ 🔧 │ │ 🟢 Gemini 2.5 Pro (Google) - Massive context - 2M tokens 👁️ 🔧 │ │ 🟡 Grok 4 Code (xAI) - Code specialist - 131K context 🔧 │ │ 🔵 DeepSeek R1 (OpenRouter) - Free tier - 64K context 🔧 │ └───────────────────────────────────────────────────────────────────────┘
Vision Capable

Models that can analyze images and screenshots

Function Calling

Models with tool execution capabilities

High Context

Models with large context windows (128K-2M tokens)

Cost Optimization

Real-time Cost Tracking

$ /cost
💰 Session Cost: $0.0023
📊 Input tokens: 1,245 ($0.0015)
📤 Output tokens: 567 ($0.0008)
🔄 Total tokens: 1,812
Free Tier Models

DeepSeek R1, Gemini 2.5 Flash via OpenRouter

Cost-Effective

GPT-4o-mini, Claude Haiku, Llama via Groq

Premium Models

GPT-5, Claude-4, Gemini 2.5 Pro

TUI Interface

Interface Overview

Rich Visual Interface

Modern TUI with real-time status, visual tool tracking, and professional branding

Smart Commands

Intelligent autocomplete, command history, and context-aware suggestions

Real-time Updates

Live cost tracking, token usage, and tool execution visualization

Interactive Elements

Enhanced Input System

  • • Multiline support with Shift+Enter
  • • Smart autocomplete with Tab completion
  • • Command history with arrow keys
  • • History autocomplete for sessions

Tool Call Features

  • • Expandable tool call details
  • • Syntax highlighting for code/JSON
  • • Progress indicators for operations
  • • Copy functionality for outputs

Command Reference

Slash Commands

/help

Show comprehensive help with all available commands and shortcuts

/help
/cost

Display detailed token usage and cost breakdown for current session

/cost
/new-chat

Clear conversation history and free up context

/new-chat
/reset

Clear conversation history (alias for /new-chat)

/reset
/clear

Clear conversation history (alias for /reset)

/clear
/compact

Clear conversation history but keep a summary in context

/compact [custom instructions]
/history

View and manage conversation history with interactive interface

/history
/setup

Run setup wizard to configure API keys, editor, model, etc.

/setup
/model

Configure AI model, provider, and API keys with interactive menu

/model
/quit

Exit the application

/quit

CLI Arguments

juno-agent [OPTIONS] [COMMAND]
--workdir, -w PATHWorking directory (defaults to current)
--debugEnable debug mode with detailed logging
--traceEnable Phoenix tracing (requires arize-phoenix)
--ui-mode TEXTUI mode: ‘simple’ or ‘fancy’
--helpShow help message

Command Examples

Basic Commands

$ juno-agent
$ juno-agent
$ juno-agent setup

Advanced Commands

$ juno-agent --debug --trace
$ juno-agent --ui-mode simple
$ juno-agent version

Keyboard Shortcuts

Global Shortcuts

Ctrl+C
Quit
Exit the application
Ctrl+Q
Quit
Exit the application
Ctrl+N
New Chat
Clear conversation and start fresh
Ctrl+R
Toggle Tool Details
Expand/collapse all tool call details
F1
History
Open conversation history viewer
F2
Copy
Copy selected text to clipboard
Ctrl+S
Toggle Selection
Enter/exit text selection mode

Input Shortcuts

Enter
Submit Message
Send message or select autocomplete option
Shift+Enter
New Line
Insert line break in multi-line input
Ctrl+J
New Line
Alternative line break shortcut
Tab
Autocomplete
Complete command or navigate autocomplete
Up Arrow
History Navigate
Navigate to previous command
Down Arrow
History Navigate
Navigate to next command
Escape
Cancel/Hide
Close autocomplete or cancel selection

Context-Specific

Enter or C
Start Chat
From Welcome Screen
S
Setup
Run setup wizard from Welcome Screen
Ctrl+W
Welcome Screen
Return to welcome from chat
/
Commands
Trigger command autocomplete

Configuration

Configuration Files

Global Configuration

# ~/.juno-agent/config.yaml
models:
  default: "gpt-5"
  providers:
    openai:
      api_key: "your-openai-key"
      models: ["gpt-5", "gpt-4o", "gpt-4o-mini"]
    anthropic:
      api_key: "your-anthropic-key" 
      models: ["claude-4", "claude-3-5-sonnet"]
    google:
      api_key: "your-gemini-key"
      models: ["gemini-2.5-pro", "gemini-1.5-flash"]
    xai:
      api_key: "your-xai-key"
      models: ["grok-4", "grok-4-code"]

ui:
  mode: "fancy"  # or "simple"
  theme: "dark"
  show_tokens: true
  show_cost: true

project:
  auto_scan: true
  languages: ["python", "javascript", "typescript", "rust", "go"]
  frameworks: ["react", "nextjs", "django", "flask", "fastapi"]

Global Configuration (~/.juno-agent/)

  • • Shared across all projects
  • • API keys and default model settings
  • • UI preferences and themes
  • • Files: config.yaml, .env, .gitignore

Local Configuration (.juno-agent/)

  • • Project-specific settings
  • • Override global settings
  • • Workspace data and libraries
  • • Setup completion status

Environment Variables

Multi-project Setup

Project-specific Configurations

# Project A (React + TypeScript)
~/projects/react-app/.juno-agent/config.yaml
default_model: “gpt-5”
context_libraries: [“react”, “typescript”, “next.js”]
ui_mode: “fancy”
# Project B (Python + Django)
~/projects/django-api/.juno-agent/config.yaml
default_model: “claude-4”
context_libraries: [“django”, “python”, “postgresql”]
ui_mode: “simple”

Tips & Tricks

Power User Features

Multi-line Input

  • • Use Shift+Enter or Ctrl+J for line breaks
  • • Perfect for code blocks and complex queries
  • • Maintains formatting in conversation
  • • Syntax highlighting for code input

Selection Mode

  • • Ctrl+S to enter text selection mode
  • • Select any text in the chat area
  • • F2 to copy selected text to clipboard
  • • Useful for extracting code snippets

Command Chaining

  • • Use /compact [instructions] for targeted summarization
  • • Combine /new-chat with immediate follow-up
  • • Chain tool calls for complex workflows
  • • Strategic context management

Model Switching

  • • Fast models (Groq) for quick questions
  • • Powerful models (Claude-4, GPT-5) for complex coding
  • • Local models (Ollama) for privacy
  • • Use /model to switch mid-conversation

Best Practices

Troubleshooting

Common Issues & Solutions

API Key Issues

Error: “Invalid API key” or “Unauthorized”

  • • Run /setup to reconfigure API keys
  • • Check environment variables are set correctly
  • • Verify API key has proper permissions
  • • Ensure no extra spaces in API key
TUI Display Issues

Garbled display or weird characters

  • • Try --ui-mode simple for compatibility
  • • Ensure terminal supports UTF-8 encoding
  • • Update terminal software if possible
  • • Use --debug flag for detailed logs
Performance Issues

Slow responses or high token usage

  • • Use /cost to monitor token usage
  • • Try faster models like Groq for simple queries
  • • Use /compact to reduce context size
  • • Enable --trace for performance analysis
Debug Mode

For detailed troubleshooting

$ juno-agent --debug --trace

Logs saved to app_run.log in current directory