Skip to main content
This guide walks you from a fresh Hiroshi installation to a working agent conversation. By the end you will have sent your first message, used slash commands to inspect the runtime state, and seen how to switch between agents. Before continuing, make sure you have completed the installation steps and have Ollama running with at least one model pulled.
If another Hiroshi instance (such as hiroshi daemon) is already running when you launch hiroshi agent, the terminal session automatically enters read-only mode. Database writes and workspace file modifications are disabled to prevent collisions, and a warning is printed at startup.
1

Start Ollama

Open a terminal and start the Ollama server if it is not already running.
ollama serve
In a separate terminal, verify that your model is available.
ollama list
If you haven’t pulled a model yet, do so now:
ollama pull qwen2.5-coder:1.5b
2

Run the onboarding wizard

Launch Hiroshi’s interactive agent mode. On the very first run, Hiroshi detects that ~/.hiroshi/config.toml is missing and starts the onboarding wizard automatically.
hiroshi agent
The wizard walks you through three prompts:
==================================================
      Welcome to the Hiroshi Onboarding Setup
==================================================

? What is your AI Companion's Name? › Hiroshi
Scanning for local Ollama models...
? Choose an Ollama Model to pair with: › qwen2.5-coder:1.5b
? Would you like to enable the Telegram Bot Gateway? › No
After you answer the prompts, the wizard writes ~/.hiroshi/config.toml, creates the default AGENTS.md, pre-populates the ~/.hiroshi/skills/ directory with bundled skills, and drops you straight into the interactive terminal.
3

Send your first message

After the wizard completes (or on subsequent runs once config exists), you will see the Hiroshi prompt showing the active agent name in square brackets.
Interactive Agent Terminal Mode started.
Type /help to see available commands or type /exit to quit.

Hiroshi [Architect] >
Type a message and press Enter. Hiroshi embeds your input, retrieves relevant memory context, and streams the response token by token.
Hiroshi [Architect] > Explain the project structure of a Rust CLI tool

Assistant [Architect] (terminal) >
A well-structured Rust CLI project typically follows this layout:

src/
  main.rs       — entry point; parses CLI args with clap
  config.rs     — configuration loading and defaults
  ...

Cargo.toml defines your dependencies and feature flags...
The response is also saved to the SQLite memory store so future turns can retrieve it as context.
4

Use slash commands

Slash commands let you inspect and control the running session without sending a message to the model. Type /help to print all available commands.
Hiroshi [Architect] > /help
Available commands:
  /agent <name> - Switch active agent
  /agents       - List all registered agents
  /skills       - List dynamic skills
  /clear        - Clear history
  /exit         - Quit
CommandDescription
/helpPrint all available slash commands
/agentsList every agent defined in AGENTS.md with its system prompt
/skillsList all registered dynamic skills and their descriptions
/agent <name>Switch the active agent to <name> for this session
/clearClear the conversation history from the database
/exitQuit the interactive terminal
5

Switch agents

Hiroshi starts with the Architect agent active by default. Use /agent to switch to a different agent defined in your AGENTS.md.
Hiroshi [Architect] > /agent Developer
Switched active agent to: Developer

Hiroshi [Developer] > Write a Rust function that reads a file and returns its lines as a Vec<String>
You can also switch agents mid-conversation by including a [HANDOFF: AgentName] token in a message. The agent loop detects the token, switches automatically, and continues the turn with the new agent’s system prompt — no slash command needed.
6

List available skills

Run /skills to see all skills currently registered in ~/.hiroshi/skills/. Hiroshi ships with five bundled skills created automatically at first run.
Hiroshi [Developer] > /skills
Discovered Skills:
  - git_manager: Orchestrates Git repo state, runs diffs, commits code changes, and manages branches.
  - browser_automation: Playwright headless browser scraping and viewport screenshots.
  - file_janitor: Tracks file hashes, lists duplicate items, structures chaotic workspace directories, and updates README file indices.
  - task_sync: Syncs project milestones, deadlines, and logs task completion states inside task markdown files.
  - web_search: Queries search engines and fetches matching page titles, snippets, and links.
Any MCP tools you have registered in config.toml also appear here, prefixed with mcp__. Agents invoke skills automatically by emitting <call_tool name="skill_name"> XML tags in their responses.

​
Next steps

Now that you have a working session, explore the rest of Hiroshi’s capabilities.

Configuration

Learn every field in ~/.hiroshi/config.toml, including model settings, security options, cron tasks, and channel tokens.

Skills

Write your own polyglot skills in Python, Bash, or PowerShell, or let an agent generate one for you at runtime.

Integrations

Connect MCP servers and enable the Telegram, Discord, or Slack gateways to chat with Hiroshi from anywhere.

Daemon mode

Run Hiroshi as a persistent background service with all gateways, the web dashboard, and the cron scheduler active simultaneously.