Getting Started

Get up and running with AGTerm in minutes.

Prerequisites

Before launching AGTerm, ensure you have:

1. At least one API key configured — AGTerm supports multiple providers, but you need at least one:

   • ANTHROPIC_API_KEY for Claude
   • GOOGLE_API_KEY for Gemini
   • OPENAI_API_KEY for Codex/GPT
   • Or any gateway provider (Groq, Together, etc.)

2. Optional CLI tools — For specific agents:

   • claude CLI for Claude Code agent
   • gemini CLI for Gemini agent
   • codex CLI for Codex agent

Launching AGTerm

From the Calliope Hub

1. Navigate to the Hub dashboard
2. Click AGTerm in the tools section
3. A new terminal session starts automatically

Via the API

Create a session programmatically:

# Create a new AGTerm session
curl -X POST http://localhost:3000/api/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "My Workspace", "agent": "agterm"}'

Response:

{
  "success": true,
  "data": {
    "session": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Workspace",
      "agent": "agterm",
      "workspaceDir": "/home/user/.agterm/workspaces/550e8400..."
    }
  }
}

Interface Overview

The AGTerm interface consists of:

Keyboard Shortcuts

Your First Interaction

Once connected, you can start chatting with the AI:

You: Help me understand the structure of this codebase

AGTerm: I'll analyze the directory structure for you. Let me explore...

[Uses shell tool to run: find . -type f -name "*.ts" | head -20]

Here's what I found:
- `/src/components/` - React components
- `/src/hooks/` - Custom React hooks
- `/src/store/` - State management (Zustand)
...

Switching Providers

Change providers on the fly using CLI commands:

# Switch to Groq for faster responses
/provider groq
/model llama-3.3-70b-versatile

# Or use a profile
/provider anthropic
/model claude-opus-4-20250514

Using Sub-agents

The AGTerm agent can spawn specialized sub-agents:

# Run a task with Claude Code specifically
/claude Refactor the authentication module to use JWT

# Use Gemini for long-context analysis
/gemini Summarize this 50,000 line log file

Session Management

Save and Resume Sessions

# Save current session
/save my-project

# Later, resume it
/resume my-project

# List all saved sessions
/sessions

# Continue most recent session
/continue

Background Jobs

For long-running tasks, use background execution:

# Submit a background job
/bg Run all tests and fix any failures

# Check job status
/jobs

# Get job output
/job abc123

Tips for Success

1. Be specific — The more context you provide, the better the response
2. Use the right model — Quick questions → Groq; Complex problems → Opus
3. Leverage sub-agents — Different agents excel at different tasks
4. Save sessions — Preserve context for multi-day projects
5. Use /ask — Ask Calliope about AGTerm features anytime

Troubleshooting

Agent Not Available

If an agent shows as unavailable, check:

curl http://localhost:3000/api/agents/claude

This returns missingEnvVars if credentials are missing:

{
  "available": false,
  "cliExists": true,
  "hasCredentials": false,
  "missingEnvVars": ["ANTHROPIC_API_KEY"]
}

Connection Issues

If the WebSocket disconnects:

• Background jobs continue running and queue output
• Reconnecting automatically resumes the session
• Use /jobs to check any background work status

Next Steps