Ciaobot

Getting started

From install to your first archived chat

About 15 minutes. You don't need to be technical, but you'll paste a command into the Terminal app.

Set up

  1. Have Claude Code or opencode signed in

    Ciaobot doesn't have its own AI account or API key. It drives an AI tool you already use, so you need one of these two installed and signed in on the computer that runs Ciaobot:

    Claude Code

    Use your Claude subscription.

    curl -fsSL https://claude.ai/install.sh | bash
claude auth login

    On Windows, in PowerShell: irm https://claude.ai/install.ps1 | iex, then claude auth login.

    Claude Code docs →

    opencode

    Use OpenAI, OpenRouter, Z.ai, Ollama Cloud, a local Ollama and many more.

    curl -fsSL https://opencode.ai/v2/install | bash
opencode auth login

    On Windows: npm install -g @opencode/cli, then opencode auth login.

    opencode providers →

    You can set up both and switch per workspace or per chat. How the two work with Ciaobot →

  2. Install Ciaobot

    On a Mac with Apple Silicon (M1 or newer, macOS 13 or later), open the Terminal app and paste:

    curl -fsSL https://github.com/raffaelefarinaro/ciaobot/releases/latest/download/install.sh | sh

    This installs the Ciaobot engine and starts it in the background. Hosting it on a Linux server instead? See Run it on a server.

  3. Follow the setup wizard

    The Ciaobot app opens by itself (you can also go to http://localhost:8443). The wizard asks for three things:

    • A folder where Ciaobot keeps your notes and memory. A new, empty folder is fine. If you already keep notes in a folder (for example an Obsidian vault), you can point it there.
    • A password for the dashboard. You'll need it to open Ciaobot from other devices.
    • Your AI tool: Claude Code or opencode.

    Once it's done, Ciaobot opens a welcome chat and can give you a tour. Just say yes.

Find your way around

The Ciaobot Home page, with a box to start a task, chats that need attention, and projects in the sidebar
Home. The workspace picker sits at the top of the sidebar, projects and their chats below; the middle has a box to start a task and lists what needs you.

Press the number keys 1, 2, … to jump between workspaces in the order they appear in the sidebar.

To limit what a workspace's agent can read on your computer, set its File access in Settings → Workspaces → Edit. More about file access →

Your first project

Think of something you'll keep coming back to, like a trip you're planning, a language you're learning or a project at work. The easiest way to create a project is to ask:

Create a project called Learning Spanish in my personal workspace. I'm a beginner, I practise 20 minutes a day, and I want to hold a simple conversation by next summer.

Ciaobot creates the project and saves that description. From now on it's sent with every chat in Learning Spanish, so you never repeat it. You can also use New next to Projects in the sidebar.

A project page: the project context box, its active chats, files and archived chats, and a Complete button
A project page: the description Ciaobot reads, the active and archived chats, and Complete for when the project is done.
Not sure whether something needs a project? If you'd want Ciaobot to remember it next week, make one. Quick one-off tasks can go in General.

The everyday habit

  1. Start a new chat in the right project

    Use New chat at the top of the sidebar and pick the project, or press ⌥+N (Alt+N on Windows and Linux). For a quick task, type it into the box on Home.

  2. Do one task

    Talk to it as you would to an assistant: "Add a dentist appointment next Tuesday at 3pm", "Give me five phrases for ordering at a restaurant".

  3. Archive it as soon as the task is done

    Use the archive button in the chat header, press ⌥+⌫, or just type "archive this chat".

    Archiving a finished chat. A memory insights row on Home shows Ciaobot reading it back and filing what's worth keeping.

  4. Glance at suggestions now and then

    Anything Ciaobot isn't sure about waits for your OK. More on memory →

Why not keep one chat going?

AI models get measurably worse as a conversation grows: details from the start get missed and unrelated topics bleed into each other. Researchers call this context rot, and Anthropic's guide to context engineering explains why a short, focused context works better. A long chat is also slower and more expensive, and Ciaobot only learns from it once you archive it. Short chats keep your assistant sharp and up to date.

Need to pick up an archived chat later? Open it and choose Continue in new chat.

Keep track of the next steps

For work you want to come back to, open Tasks in the sidebar and choose New task. Try Compare three Spanish conversation classes, with a description of your budget, availability and what a useful comparison should include. Choose your Learning Spanish project to keep it with the right context.

Open the task and choose Delegate to agent. Review the prompt, then start the work. Ciaobot opens a chat where you can follow along and answer questions. When the agent reports it finished, check the result and choose Approve Done.

You can also do tasks yourself and move them through To do, In progress, In review and Done. More on Tasks →

Let it work on a schedule

Ask yourself: is this a task I do more than once? If it is, make it a schedule instead of typing the same request again next week.

Ask for anything that should happen regularly:

Every weekday at 8am, look at my calendar and tell me what's coming up today.
Every Sunday evening, give me ten new Spanish words based on what I practised this week.

Ciaobot shows you a draft (when it runs, and in which project) and asks before creating it. Each run leaves its result in a chat. You can see and pause everything on the Automations page, which also lists your Webhook triggers (runs started by another tool).

That's the whole routine. For everything else, see what it can do → or just ask it "what can you do?"

The Automations page listing custom and system routines with their next runs
The Automations page lists every recurring task with its next run, including the nightly memory tidy-up.

Questions

What does it cost?

Ciaobot is free and open source. You pay only for the AI you already use: a Claude subscription, an API key, or nothing at all with a local model.

What leaves my computer?

The messages you send, plus the context each chat needs, go to the AI provider you chose. Your notes, memory and chat history stay in your folder. With a local model through opencode, nothing leaves at all.

Does it work offline?

With a local model (for example Ollama) through opencode, yes. Google, web search and cloud models need a connection, of course.

Something's wrong. Where do I look?

Ask Ciaobot first ("why did my morning agenda not run?"); it can read its own logs and diagnose most problems. It can also report the bug on GitHub for you.

I forgot my Ciaobot password. Where do I find it?

The password is the one you chose in the setup wizard. Ciaobot keeps it on the computer it runs on (the host), in a file called .env inside your Ciaobot folder, on the line that starts with PWA_AUTH_TOKEN=. Everything after the = is your password.

  1. On the host computer, open the folder you picked during setup.
  2. Open the file .env in a text editor. It is a hidden file: on a Mac, press Cmd Shift . in Finder to show it. Or run grep PWA_AUTH_TOKEN ~/path/to/your/folder/.env in the Terminal.
  3. Copy the text after PWA_AUTH_TOKEN= and paste it into the login page.

Can't open the file? On the host, run ciao setup-url --workspace ~/your-folder in the Terminal, using the folder you picked during setup. It prints a one-time link that signs you in when opened in a browser on that same computer.

Once you are in, you can choose a new password in Settings → PWA password. Keep that file to yourself: anyone with the password can use your Ciaobot.

How do I update or uninstall?

To update, run the one-line install command again, or use Settings → General in Ciaobot, which installs the new engine for you. To stop Ciaobot, run ciao service stop in the Terminal; your notes folder is kept. If you are still on the old macOS app, run the one-liner with --migrate: it installs the engine and removes the old app for you.