Getting Started

Three minutes from install to your first completed task.

1. Install & open

Install Agent 24, open it, and grant the accessibility permission when prompted (required for screen understanding and UI dumping).

2. Connect a provider

Run /connect and pick from 13 pre-configured providers — OpenCode Zen, Pollinations (free), OpenAI, Anthropic, Google, Groq, DeepSeek, Mistral, xAI, Together, OpenRouter, HuggingFace, GitHub Models. Free options work with zero setup.

3. Choose a model

/model lists every model of the connected provider with capability flags: supportsTools, supportsImages, supportsReasoning, supportsStreaming.

4. Start working

Just type the task in natural language:

> build a calculator app with history
> find every TODO in src/ and summarize
> refactor utils.js and run the tests

Keyboard

Agents

Primary/sub agents you select, plus system agents that trigger automatically.

System agents

Permission matrix

allow = run silently · ask = confirm popup · deny = blocked

Tools

31 built-in tools. Every tool takes a JSON parameter map.

Execution flow

user action → check permission rules
  → deny  → blocked immediately
  → ask   → confirmation popup → wait for user
  → allow → action runs

Example calls

bash    { "command": "ls -la" }
read    { "path": "/path/to/file" }
edit    { "path": "...", "oldString": "find", "newString": "replace" }
grep    { "pattern": "regex", "path": "/dir", "include": "*.md" }
task    { "description": "...", "prompt": "...", "subagent_type": "explore" }

Commands

25+ slash commands for session and workflow control.

Permissions

Every tool call passes through the permission layer before executing.

Permission keys

Values

Evaluation order

1. Check agent-specific permission for the tool name
2. Check wildcard (*) permission
3. Default: allow (build) / ask (plan)

Providers

13 pre-configured providers with capability flags and auto-fallback.

Model capabilities

Error handling

Retry: max 3 attempts, exponential backoff 2s → 4s → 8s (429: 5s → 10s → 15s), auto-fallback to Pollinations on 4xx/5xx.

Settings

Runtime configuration lives in ~/.config/agent24/.

Useful toggles

• show_reasoning — thinking card visibility
• auto_summarize — auto-summary on session switch
• compaction_threshold — token % that triggers compaction (default 80)
• Theme — change with /theme (picker dialog)

See also: Skills, MCP, Hooks.

Skills

Markdown instruction files loaded into the system prompt on demand.

Location

~/.config/agent24/skills/<name>.md

Usage

Load with the skill tool or ask the agent directly — it pulls the file into context:

{ "tool": "skill", "params": { "name": "settings-customization" } }

Structure

• One markdown file per skill
• Loaded skills are listed at the bottom of the system prompt
• Related assets can sit next to the file
• List everything with /skills

Example

# settings-customization
How to modify agent24.json safely: keys, defaults,
restart behavior and rollback steps.

MCP

Model Context Protocol — connect external tool servers.

Registering a server

{
  "server": "my-server",
  "instructions": "shown to the model in the system prompt",
  "tools": [ { "name": "create_issue", "inputSchema": { ... } } ]
}

Calling any of these tools routes the result back to the model.

Naming

MCP tools are prefixed with mcp_{serverName}_{toolName} so they never collide with built-ins.

mcp_github_create_issue
mcp_slack_send_message

Flow

1. Server registers tools & instructions
2. Instructions join the system prompt
3. Tool definitions join the API tool list
4. Model calls mcp_* → routed to the server

Hooks

Deterministic actions that run on lifecycle events — no model involved.

Event system

session.created(sessionId)
session.loaded(sessionId)
session.deleted(sessionId)
session.renamed(sessionId, newTitle)

Typical uses: telemetry, auto-backup before edits, audit logging, custom notifications.

Sessions

Every conversation is an isolated session with its own database.

Lifecycle

startNewSession()  → id "session_" + timestamp → metadata → session database → event
loadSession(id)    → set current → load messages → update timestamp → event
deleteSession(id)  → drop database + folders + metadata → clear memory → event

Storage

Message senders

Auto features

Queue

If the session is busy, messages go into a ConcurrentLinkedQueue and show Queued (N pending) — they run right after the current task completes.

Troubleshooting

Still stuck?

Open a session and ask — the agent can read its own logs via bash and the global database at ~/.local/share/agent24/databases/.