Quick start

Create your first Jazz agent and start automating tasks in minutes.

This guide will walk you through creating your first Jazz agent and having your first AI-powered conversation.

Create your first agent

1. Launch the Jazz wizard

   Start Jazz by running the command with no arguments:

   jazz
   

   On first run, you’ll see a welcome message and be prompted to configure desktop notifications. Jazz will also detect any API keys you have set as environment variables.

   If you have OPENAI_API_KEY, ANTHROPIC_API_KEY, or other provider keys in your environment, Jazz will automatically detect them.

2. Select 'Create agent'

   From the main menu, choose Create agent. Jazz will launch an interactive wizard to guide you through the setup.

   You’ll be prompted for:

   • Agent name - A friendly identifier (e.g., “dev-assistant”, “research-bot”)
   • Description - What this agent is for (e.g., “Helps with code reviews”)
   • LLM provider - Choose from OpenAI, Anthropic, Google, and more
   • Model - Select the specific model (e.g., gpt-4, claude-3-opus-20240229)
   • Persona - Optional personality and behavior template
3. Start chatting

   Once your agent is created, Jazz will automatically start a conversation. You can now chat with your agent using natural language:

   > What files are in the current directory?
   

   Your agent will use its tools to read the filesystem and respond with the information you requested.

   Jazz agents require approval before executing potentially dangerous operations like writing files, running shell commands, or making git commits. Safe operations like reading files happen automatically.

4. Try a complex task

   Let’s try something more interesting. Ask your agent to analyze your project:

   > Find all TODO comments in this project and create a summary
   

   Your agent will:

   1. Search for TODO comments across your codebase
   2. Parse and categorize them
   3. Create a formatted summary

   You can approve or deny each step that requires permission.

Essential commands

Once you’re chatting with an agent, you have access to special commands that start with /:

Command	Description
/help	Show all available commands
/exit	End the conversation
/clear	Clear conversation history
/tools	List available tools
/skills	Show loaded skills
/model	Switch to a different model
/context	View current context size
/cost	Show token usage and costs

Type /help during any conversation to see the full list of available commands.

Common workflows

Here are some practical tasks you can try with your new agent:

Code review

> Review the last commit and flag any potential issues

Git operations

> Create a commit with all my changes and write a good commit message

Research and summarization

> Search the web for the latest TypeScript 5.4 features and summarize them

File operations

> Find all files larger than 1MB in this directory

Email management

> Check my unread emails and summarize the important ones

For email operations, you’ll need to authenticate with Gmail using jazz auth gmail login.

Manage multiple agents

You can create multiple agents for different purposes. Each agent has its own configuration, conversation history, and behavior.

List all agents

jazz agent list

Chat with a specific agent

jazz agent chat <agent-name>

Edit an existing agent

jazz agent edit <agent-name>

Delete an agent

jazz agent delete <agent-name>

Understanding agent personas

Personas define your agent’s personality, expertise, and behavior. Jazz includes several built-in personas:

• Developer - Code-focused, technical expertise
• Researcher - Deep research, analysis, and documentation
• Assistant - General-purpose helper
• Writer - Content creation and editing

You can also create custom personas:

jazz persona create

Personas can define:

• System prompts and instructions
• Available tools and skills
• Response style and tone
• Auto-approval policies

Agent configuration

Agents are stored as JSON files in ~/.jazz/agents/. Each agent has a configuration that includes:

{
  "id": "agent-123",
  "name": "my-assistant",
  "description": "General purpose assistant",
  "provider": "openai",
  "model": "gpt-4-turbo-preview",
  "config": {
    "persona": "assistant",
    "temperature": 0.7,
    "maxTokens": 4096
  }
}

You can view an agent’s configuration:

jazz agent show <agent-name>

Add MCP servers

Extend your agent’s capabilities by connecting MCP (Model Context Protocol) servers. MCP servers provide access to external services like Notion, GitHub, Linear, and more.

Add an MCP server

jazz mcp add

You’ll be prompted to enter the MCP server configuration as JSON:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

List configured MCP servers

jazz mcp list

Enable or disable MCP servers

jazz mcp enable
jazz mcp disable

Next steps

Now that you have your first agent running, explore more advanced features:

Agent concepts

Learn advanced agent configuration and management

Workflows

Automate recurring tasks with scheduled workflows

Skills

Extend agents with specialized skills

MCP integration

Connect to external services via MCP

Getting help

If you run into issues or have questions:

• Type /help in any conversation for in-chat commands
• Run jazz --help for CLI command reference
• Check the GitHub issues
• Join the Discord community

Press Ctrl+P in your terminal to see available actions and shortcuts.