Skip to main content

Quick Start

This page walks you from a fresh install to the core Bossanova flow: add a repo, start agent work, chat with the agent, follow pull request and CI state, schedule recurring sessions, archive finished work, clean up old chats, and sign in to Bossanova Cloud when you want browser access.

Skip steps you've already done; cross-links point at the relevant settings or guide page where one exists.

1. Install​

Bossanova ships prebuilt binaries for macOS (Intel and Apple Silicon) and Linux x86_64. Pick your platform:

Install with Homebrew:

brew install bossanova-dev/tap/bossanova

Then register the daemon service:

boss daemon install

Check that the daemon is running:

boss daemon status

Expected output (the service path is a launchd plist on macOS and a systemd unit on Linux; PID and path vary by machine):

Daemon is running.
  PID:     11537
  service: ~/Library/LaunchAgents/com.bossanova.bossd.plist

The daemon owns session state, worktree cleanup, GitHub sync, and browser access.

2. Open boss for the first time​

Launch the terminal UI:

boss

The home screen is the control center for active coding-agent work. It shows sessions across repositories, with branch, pull request, review, and CI state in one place.

On a fresh install, the repo list starts empty.

3. Add a repo​

Press s to open Settings, then r to load the repository list, then press a to add a new repository. Provide the path to a local folder if you already have the repository checked out. Provide a GitHub URL if you want to check out a repository that you do not yet have locally.

You can open an existing checkout or clone from a URL.

4. Configure repo settings​

Open the repo settings before your first serious session. Confirm the base branch, worktree directory, agent, and PR behavior match how this repo ships.

See Agent Plugins and Settings for the full configuration surface.

5. Start a session​

Press n from the home screen.

The new-session flow asks for the repo, agent, and task. Bossanova creates the branch and worktree before handing the prompt to the agent.

Pick the session type that matches the job:

  • PR session for implementation work that should land through GitHub.
  • Quick Chat for lightweight questions or repo exploration.
  • Linear when you want to start from an issue.
  • Sentry when you want to start from an unresolved error. (Shown once the repo has Sentry credentials set in its Integrations settings.)

6. Chat with the agent​

Open a session and attach to the chat.

Use the chat pane when the agent needs direction, review, or a final decision. Bossanova keeps the session state visible without turning every interaction into a separate shell workflow.

Use Ctrl-X to detach from a session and leave it running, or use Ctrl-C twice to stop the session and exit.

7. Watch PR and CI state​

Return to the dashboard to see whether work is running, waiting for review, blocked on CI, or ready to merge.

For the full pull request flow, see PR Lifecycle.

8. Set up scheduled jobs​

Press s to open Settings, then c to open the scheduled sessions view and create recurring agent work.

Scheduled jobs are useful for repeated maintenance: dependency checks, weekly cleanup, release prep, or any coding task that starts from the same prompt.

See Scheduled Sessions for schedule format and failure behavior.

9. Archive finished work​

Select a completed session with enter, then press a from the session view (beside the merge action).

Archiving removes the local worktree while keeping the branch and pull request history available.

10. Clean up old chats​

Press s to open Settings, then t to open Trash, where you can review archived chats and permanently delete the ones you no longer need.

Archiving keeps completed work out of the active dashboard. Trash gives you the final cleanup step when a branch, PR, or chat history is no longer useful.

11. Sign in to Bossanova Cloud​

Sign in from the TUI when you want browser access to the same local sessions.

Bossanova Cloud is a paid add-on to the free Bossanova client. It lets you manage coding sessions remotely from the web and manage boss sessions on multiple machines in one place. Sessions are securely streamed to the browser so you can work from anywhere.

See Web App for the full cloud setup.

Next steps​