Quickstart

This guide walks through a first task in the desktop app: add a repository, start a worker, follow its work, and review the result.

Before you start

Install Tallpine and sign in with gh if you use a GitHub project. If you choose an external coding agent, install it and complete its sign-in. Tallpine calls these tools harnesses. Unreal Agent is built in for Chat on macOS and Linux. See Installation.

Pick a safe first task

Choose a repository where you can create a branch and pull request. Good first tasks have a clear finish line:

Fix a small bug with a reproducible failure.
Add one focused test.
Update a short documentation page.
Make a narrow refactor with explicit acceptance criteria.

Run the first session

Add the repository

Open Tallpine, choose Add project, and select the local repository. The desktop app registers it and keeps the original checkout intact.

Create a worker

Create a new task from the project and enter a short name plus a specific prompt. Select an available coding agent. External agents appear after installation; Unreal Agent is built into Tallpine for Chat on supported macOS and Linux. Tallpine lists agents under Harness in Settings.

Choose the interface that fits the task:

Chat for structured conversation, activities, approvals, plans, and durable history.
Terminal UI for the harness's native interactive terminal.

Tallpine creates an isolated git worktree and branch for the session before launching the selected controller.

Follow the session

Select the session in the sidebar or board. The main pane shows its Chat conversation or live terminal. The inspector shows session details, pull-request state, reviews, changed files, and browser preview.

Tallpine combines activity such as active, idle, waiting for input, blocked, or exited with pull-request facts to show the session's status.

Give feedback

Use the Chat composer or session message controls for follow-up instructions. Keep corrections concrete:

Keep this change limited to the API route. Do not refactor the shared client.

For a TUI session, the terminal remains available when direct interaction is needed.

Review the pull request

After the worker opens or claims a pull request, Tallpine shows a concise summary of CI, reviewers, unresolved review comments, and mergeability. You can run a reviewer agent, send requested changes back to the worker, resolve comments, or merge when appropriate.

Tallpine never force-deletes a dirty worktree. Cleanup preserves user work when it cannot safely remove a session workspace.

Try a browser preview

For a web task, start the app inside the session and select its URL with the optional CLI:

tallpine preview http://127.0.0.1:5173

If the repository includes .ao/launch.json, tallpine preview start can start a configured development server. The Browser tab then displays the selected target. Tallpine does not guess a preview target merely because a worker exists.

Try switching interfaces

Supported sessions show Switch to chat UI or Switch to terminal UI. The option depends on the agent and whether it is working. Tallpine keeps the same session and worktree while it replaces one controller at a time.

If offered, Finish work, then switch waits for accepted work. Stop now and switch interrupts it. Some terminal sessions require Terminate and then switch. Read the dialog because drafts, attachments, or queued turns may need to be sent again. See Dashboard: switch interfaces for details about conversation history.

Optional CLI

The CLI is a thin client for the app-owned daemon. It is useful for scripting and terminal-first workflows, but is not required for normal desktop use.

tallpine status
tallpine session ls
tallpine send --session <session-id> --message "Run the focused tests before you finish."

Choose the default interface in Settings → General, or choose one for the new task. Project agent settings choose the coding agent, model, reasoning effort, and provider execution mode. They do not set the global Chat or Terminal UI default.