Quickstart

Get your first AI agent interaction up and running in minutes. This guide walks you through installation, setup, and your first conversation with Grip AI.

Prerequisites

Before you begin, make sure you have:

Python 3.12 or higher installed
uv package manager
An Anthropic API key (for Claude Agent SDK) or an API key from another LLM provider

Grip AI uses the Claude Agent SDK by default for the best agentic experience. You can also use LiteLLM engine for 15+ other providers (OpenAI, DeepSeek, Groq, Gemini, Ollama, etc.).

Installation

Install Grip AI

Choose your preferred installation method:

# Using uv (faster)
uv tool install grip-ai

# Using pip
pip install grip-ai

Installing from PyPI is the fastest way to get started. The source installation is useful for development or customization.

Run the onboarding wizard

The interactive setup wizard configures everything you need:

grip onboard

The wizard will:

Ask you to choose your engine: Claude Agent SDK (recommended) or LiteLLM (15+ providers)
Prompt for your API key (Anthropic, OpenAI, or other provider)
Help you select a default model
Initialize the workspace at ~/.grip/workspace/
Test connectivity to ensure everything works

Example interaction:

Welcome to Grip AI Setup!

Choose your engine:
  1. Claude Agent SDK (recommended for Anthropic models)
  2. LiteLLM (for OpenAI, DeepSeek, Groq, Gemini, Ollama, etc.)

Selection [1]: 1

Enter your Anthropic API key: sk-ant-...
Choose a model [claude-sonnet-4]: 

Testing connection... ✓
Workspace initialized at ~/.grip/workspace/

Setup complete! Try: grip agent

Verify installation

Test that Grip AI is ready:

grip status

You should see output confirming your configuration and workspace location.

Your First Conversation

Start interactive chat

Launch the agent in interactive mode:

grip agent

You’ll see a prompt where you can start chatting with the AI.

Try some commands

grip agent -m "What files are in my workspace?"

The agent will use its built-in tools (file operations, shell execution, web search, etc.) to complete tasks autonomously.

Interactive Mode Commands

When running grip agent in interactive mode, you have access to these slash commands:

Command	Description
`/new`	Start a fresh conversation
`/clear`	Clear conversation history
`/undo`	Remove last exchange
`/rewind N`	Rewind N exchanges
`/compact`	Compress session history to save tokens
`/copy`	Copy last response to clipboard
`/model <name>`	Switch AI model (e.g., `/model openai/gpt-4o`)
`/provider`	Show current provider details
`/tasks`	Show scheduled cron tasks
`/trust <path>`	Grant agent access to a directory
`/trust revoke <path>`	Revoke agent access to a directory
`/status`	Show session info (model, message count, memory)
`/mcp`	List MCP servers
`/doctor`	Run diagnostics
`/help`	List all commands
`/exit`	Exit grip

Use /trust <path> to grant the agent access to directories outside its workspace. By default, Grip AI is sandboxed to ~/.grip/workspace/ for security.

Starting the Gateway

The gateway is Grip AI’s long-running process that connects everything — Telegram bots, Discord, Slack, cron jobs, the REST API, and more.

Launch the gateway

grip gateway

You should see:

Channels started: []
API server started: http://127.0.0.1:18800
grip gateway running. Press Ctrl+C to stop.

If you haven’t configured any channels (Telegram, Discord, Slack), the gateway will still start the REST API on port 18800.

Verify the API is running

Test the health endpoint:

curl http://localhost:18800/health

You should get a success response:

{"status": "ok"}

Testing the API

The REST API requires authentication with a bearer token. On first run, Grip AI auto-generates a token and prints it to the console.

Find your API token

When you first run grip gateway or grip serve, look for output like:

Generated new API token: grip_abc123xyz...
Save this token — it won't be shown again.

Save this token immediately. It won’t be displayed again. You can regenerate it by deleting ~/.grip/config.json and restarting, but this will reset your configuration.

Make an authenticated request

Use the token to send a chat message:

curl -X POST http://localhost:18800/api/v1/chat \
  -H "Authorization: Bearer grip_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'

The agent will respond with a JSON object containing its response.

Explore other endpoints

curl -H "Authorization: Bearer grip_YOUR_TOKEN" \
  http://localhost:18800/api/v1/tools

For a full list of API endpoints, see the API Reference.

Common Tasks

Switch AI Models

You can switch models at any time:

# In interactive mode
/model openai/gpt-4o

# Via config
grip config set agents.defaults.model "openrouter/google/gemini-2.5-pro"

# For a single request
grip agent -m "Analyze this code" --model "anthropic/claude-sonnet-4"

Grant Directory Access

Grip AI is sandboxed to its workspace by default. To work with files outside ~/.grip/workspace/, you must explicitly trust directories:

# In interactive mode
/trust ~/Downloads

# In CLI
grip agent
> /trust ~/projects/myapp

The agent will remember trusted directories across sessions. Learn more about Grip’s security model in the Security documentation.

Set Up Telegram

Connect Grip AI to Telegram for mobile access:

Create a bot with BotFather

Open Telegram and search for @BotFather
Send /newbot and follow the prompts
Copy the bot token (looks like 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

Configure Grip AI

grip config set channels.telegram.enabled true
grip config set channels.telegram.token "YOUR_BOT_TOKEN"

Optional: Restrict the bot to specific Telegram user IDs for security:

# Find your user ID by messaging @userinfobot
grip config set channels.telegram.allow_from '["YOUR_TELEGRAM_USER_ID"]'

Start the gateway

grip gateway

You should see:

Channels started: telegram
API server started: http://127.0.0.1:18800
grip gateway running. Press Ctrl+C to stop.

Chat with your bot

Open Telegram, find your bot, and send /start. You can now chat with Grip AI from your phone!

See the Telegram Channel documentation for more details.

Schedule Recurring Tasks

Create cron jobs that run automatically:

# Daily standup reminder
grip cron add "standup" "0 9 * * 1-5" "Remind the user: standup in 15 minutes"

# Check disk usage every 6 hours
grip cron add "disk-check" "0 */6 * * *" "Check disk usage and report if over 80%"

# List all jobs
grip cron list

# Disable a job
grip cron disable <job-id>

When you create a cron job while chatting via Telegram, the agent automatically sets --reply-to so results are delivered back to your chat.

Create Multi-Step Workflows

For complex tasks, the agent automatically creates a task list using the todo_write tool. You can view active tasks:

# In interactive mode
/tasks

# Check the task file directly
cat ~/.grip/workspace/tasks.json

The agent updates task statuses (pending, in_progress, completed) as it works, and the active task list is automatically injected into every prompt so it never loses track — even across long sessions with context compaction.

Troubleshooting

Command not found: grip

Solution:If you installed via uv tool install, make sure the uv bin directory is in your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

API authentication failed

Solution:

Make sure you’re using the correct token from the initial gateway startup
Check that the Authorization header format is correct: Bearer grip_YOUR_TOKEN
Verify the token in your config: grip config show | grep auth_token

Agent can't access my files

Solution:Grip AI is sandboxed to ~/.grip/workspace/ by default. You need to explicitly trust directories:

/trust /path/to/your/project

View trusted directories with /trust (no arguments).

Gateway won't start (port in use)

Solution:If port 18800 is already in use, you can change it:

grip config set gateway.port 18801
grip gateway

Telegram bot not responding

Solution:

Verify your bot token: grip config show | grep telegram
Check that Telegram is enabled: grip config set channels.telegram.enabled true
Restart the gateway: grip gateway
Check gateway logs for errors

Model not found or API error

Solution:

Verify your API key is set correctly: grip config show
Check that you’re using the correct model identifier for your provider
For Claude models, use claude_sdk engine (default)
For other providers, switch to litellm engine:

grip config set agents.defaults.engine "litellm"

Next Steps

Channels

Connect Grip AI to Telegram, Discord, or Slack

API Reference

Explore the full REST API

Configuration

Customize models, tools, and security settings

Security

Learn about Grip’s security architecture

Getting Started

Core Concepts

Channels

Features

Configuration

Deployment

Advanced

Prerequisites

Installation

Your First Conversation

Interactive Mode Commands

Starting the Gateway

Testing the API

Common Tasks

Switch AI Models

Grant Directory Access

Set Up Telegram

Schedule Recurring Tasks

Create Multi-Step Workflows

Troubleshooting

Next Steps

Channels

API Reference

Configuration

Security

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Channels

Features

Configuration

Deployment

Advanced

​Prerequisites

​Installation

​Your First Conversation

​Interactive Mode Commands

​Starting the Gateway

​Testing the API

​Common Tasks

​Switch AI Models

​Grant Directory Access

​Set Up Telegram

​Schedule Recurring Tasks

​Create Multi-Step Workflows

​Troubleshooting

​Next Steps

Channels

API Reference

Configuration

Security

Build docs developers (and LLMs) love

Prerequisites

Installation

Your First Conversation

Interactive Mode Commands

Starting the Gateway

Testing the API

Common Tasks

Switch AI Models

Grant Directory Access

Set Up Telegram

Schedule Recurring Tasks

Create Multi-Step Workflows

Troubleshooting

Next Steps