Quickstart

This guide walks you through creating a project, setting up an agent, and having your first conversation — all in under 5 minutes.

1. Initialize a Project

Create a new directory and initialize supyagent:

mkdir my-project && cd my-project
supyagent init

This creates:

agents/ — Your agent YAML configurations
powers/ — Your tool scripts (pre-populated with default tools)
.supyagent/ — Session data, credentials, and registry

You'll see default tools installed: shell.py, files.py, edit.py, search.py, find.py, patch.py, git.py, plan.py, web.py, and browser.py.

2. Create an Agent

supyagent new myagent

This creates agents/myagent.yaml:

agents/myagent.yaml

name: myagent
description: ""
version: "1.0"
type: interactive

model:
  provider: anthropic/claude-sonnet-4-5-20250929
  temperature: 0.7

system_prompt: |
  You are a helpful AI assistant.
  You have access to tools that let you interact with the local filesystem,
  run shell commands, search code, and browse the web.
  Use these tools to help the user accomplish their tasks.

tools:
  allow:
    - "*"

delegates: []

Customize the Model

If you're using a different provider, edit the model.provider field:

model:
  provider: openai/gpt-4o           # OpenAI
  provider: google/gemini-2.5-flash  # Google
  provider: ollama/llama3.2          # Local Ollama

3. Start Chatting

supyagent chat myagent

You'll see:

╭─ myagent ─────────────────────────────╮
│ Model: anthropic/claude-sonnet-4-5... │
│ Tools: 35 available                   │
│ Session: a1b2c3d4                     │
╰───────────────────────────────────────╯

You: _

Try asking your agent to do something:

You: List all Python files in this directory and count the lines in each one

The agent will use the shell and files tools to execute the task, showing you the tool calls and results as it works.

4. Useful Chat Commands

Inside the chat, type /help to see all commands:

Command	Description
`/tools`	List all available tools
`/history 5`	Show last 5 messages
`/tokens`	Toggle token usage display
`/new`	Start a fresh session
`/sessions`	List all past sessions
`/export chat.md`	Export conversation to markdown
`/quit`	Exit the chat

5. Run in Execution Mode

For automation, use supyagent run instead of chat:

supyagent run myagent "List all Python files and count lines in each"

This runs the agent non-interactively and prints the result to stdout. Perfect for scripts and pipelines.

# JSON output for parsing
supyagent run myagent "What's in README.md?" --output json

# Pipe input from a file
supyagent run myagent --input task.txt

# Quiet mode (result only)
supyagent run myagent "Summarize this repo" --quiet

What's Next?

Core Concepts — Understand agents, tools, sessions, and delegation
Building Agents — Deep dive into agent configuration
Building Tools — Create custom tools with supypowers
Cloud Integrations — Connect to Gmail, Slack, GitHub, and more

Quickstart

On this page