Key Concepts

Tips

• Think workspace-first, not chat-first. Intent is built around workspaces, not conversations. Treat it as “the place where one task lives,” not “where I talk to an agent.”
• Use one workspace per real task. Each workspace gets its own Git worktree for isolation. If the work is separate, the workspace should be separate.
• Don’t create a new workspace for every agent chat. Multiple specialist agents can collaborate within a single workspace.
• Invest in setup scripts early. Build reliable bootstrapping scripts for fresh worktrees.
• Use the built-in browser as part of the workspace. Keep your running app, test flows, and visual checkpoints attached to the workspace.
• Customize your specialist agents. Shape their prompts to match your actual workflow.
• Mix models across specialists. Assign different providers or models to different roles, such as one for coordination and another for verification.
• Think in orchestration, not single-agent magic. Decide what specialists and context the workspace needs.

Setup

1. Go to Settings → Providers to configure your agent provider (Augment Auggie, Anthropic Claude Code, Grok Build, OpenAI Codex, OpenCode, Pi, or Unsloth) and default model — the first-run onboarding walks you through this.
2. Create a new workspace for each task.
3. Point it at an existing repo and choose to work off the main branch in a new worktree, or check Work directly to work in the folder itself.

Getting Started

Intent is a desktop app for AI-assisted software development. You work inside workspaces — each one wraps a git branch with its own AI agents, notes, and file tracking. You describe what you want built, and agents write a spec then implement the code.

Install & Launch

1. Download Intent for macOS, Windows (Alpha), or Linux (Alpha)
2. Open the app — click the Intent logo in the title bar (or press Cmd+O) to open the global sidebar, which lists all your workspaces

Prerequisites

• Intent works with agent providers — Augment Auggie, Anthropic Claude Code, Grok Build, OpenAI Codex, OpenCode, Pi, and Unsloth. You’ll need at least one to use Intent.
• Install an agent provider and log in to it with your account.
• Intent will prompt you to install Node.js 22+ (nodejs.org) and Git (git-scm.com) if you don’t already have them.

Create Your First Workspace

Open the global sidebar and click the + button — or press Cmd+N anywhere — to start a new workspace. Intent asks “What repo should we work on?” — select an existing codebase or make a new one, and it creates an isolated workspace to work in. Pick one of:

• Pick a repo — Choose one of your GitHub repos (or paste a URL); Intent clones it for you
• Copy local repo — Point at a git repo on your machine; Intent works in an isolated copy, leaving your folder untouched
• New repo — Create a brand-new local git repository from scratch

Each workspace gets its own git branch automatically, so your main branch stays untouched. The new-workspace form also lets you:

• Team or single agent — the default is a Coordinator-led team (Coordinator + Implementor + Verifier); switch to a single specialist for smaller tasks
• Model — pick a per-provider model, with an optional reasoning-effort level
• Branch — choose the base branch, or check Work directly to skip branch isolation
• Scope — point the workspace at a subdirectory of a monorepo
• Remote machines — run the workspace on a connected remote machine instead of locally

Have Your First Conversation

Once inside a workspace:

1. Type a prompt in the chat input at the bottom — describe what you want
2. Watch the agent work — it reads your code, edits files, runs commands, and streams its thinking in real time
3. Review the changes — open the Changes panel in the sidebar to see file diffs
4. Accept or adjust — if the changes look right, commit them. If not, tell the agent what to fix.

That’s the core loop: prompt → agent works → review → iterate.

What to Try Next

• Write a Spec to give the agent a structured plan (see Context)
• Use a specialist like the Coordinator to break big projects into tasks (see Agents & Chat)
• Open the terminal with Ctrl+` to run commands alongside the agent

Key Terms

Workspaces

A workspace is your project’s home base in Intent. It bundles a git branch, AI agents, notes, and an activity log into one isolated environment. You can have many workspaces open — one per feature, bug fix, or experiment.

Creating a Workspace

Open the global sidebar (Intent logo or Cmd+O) and click the + button — or press Cmd+N anywhere — then choose:

Intent creates a dedicated git branch — with an optional, configurable prefix (Settings → Setup → Git & Workspace) — so your main branch is never touched directly.

The Global Sidebar

Click the Intent logo in the title bar (or press Cmd+O) to open the global sidebar — a combined panel with the All Workspaces list on top and the Intent App agent chat below, separated by a resizable divider.

All Workspaces lists every workspace across all your repositories, grouped by Recent, Repo, or Status (In Progress, Needs Attention, PR Open, Completed, and more). You can search the list and show or hide archived workspaces. Each card shows:

• Workspace name, status message, and phase indicator
• Branch name and repo
• Agent activity summary and unread indicators
• Task progress (if a Spec has tasks)

Pin workspaces to keep them at the top, and Cmd/Ctrl-click a card to open it in a new window. For a mission-control view of every workspace and its agents, open the Fleet HUD with Cmd+Shift+H.

The Intent App agent is an app-level assistant that works across the whole app rather than inside one workspace. Ask it to manage workspaces (create new ones, archive or clean up stale ones), tune settings, coordinate specialists, prepare a daily brief, or spin up workspaces for the PRs assigned to you. Conversations are kept as threads you can return to or delete.

Switching Between Workspaces

• Cmd+O — Toggles the global sidebar. Type to search, click to switch.
• Ctrl+Tab / Ctrl+Shift+Tab — Cycle through recent workspaces.
• Alt+Shift+←/→ — Reorder workspace tabs.

The Workspace Sidebar

Once inside a workspace, the left sidebar has several tabs:

Toggle the sidebar with Cmd+B.

Managing Workspaces

• Rename — Click the workspace title in the sidebar header to edit it
• Pin — Keep important workspaces sorted first in the global sidebar’s workspace list
• Archive — From the global sidebar (or by asking an agent), archive workspaces you’re done with
• Delete — Permanently remove a workspace and its metadata

Workspace Settings

Each workspace can have its own:

• Git configuration — Remote, base branch
• MCP servers — Extra tool servers for agents
• Setup scripts — Commands that run when the workspace initializes

Agents & Chat

Agents are AI assistants that live inside your workspace. They read your code, edit files, run terminal commands, and use tools — all while streaming their work to you in real time.

Starting an Agent

• Cmd+T — Opens a new panel where you start an agent
• Select the kind of specialist to start (Coordinator, Developer, and any custom ones)
• Type your prompt and press Enter to send — Cmd+E enhances the prompt first
• Cmd+Shift+A — Attach files to the message (or drag and drop them into the chat)
• Attach and view images and video inline in chat
• Prefer talking? Voice dictation can be enabled in Settings → Input

You can have multiple agents running simultaneously in the same workspace.

Reviewing Agent Work

• Changes panel — Shows all modified files as diffs
• Click a file — Opens a side-by-side diff view
• Accept — Commit the changes
• Reject — Tell the agent what to fix, or undo

Controlling Agents

Specialists

Not all agents are the same. Specialists are agents pre-configured for specific roles — each with its own behavior, provider, and model. Pick one from the agent picker when you start an agent, or let a Coordinator delegate to them for you.

Create Your Own Specialists

The built-in specialists are just a starting point — you can create your own to match how you actually work. In Settings → Specialists, give a specialist a name, a behavior prompt, and its own provider and model. It then appears in every agent picker and can be delegated to by a Coordinator, just like the built-ins.

Custom specialists are how you encode your team's conventions, review standards, or domain expertise into a reusable role — a "Migration Writer," a "Security Reviewer," a "Docs Editor" — so the right agent shows up already primed for the job.

Multi-Agent Workflows

Specialists work together on a single task inside one workspace:

1. Describe the goal to a Coordinator.
2. It writes a plan in the Spec with task blocks.
3. You approve the plan.
4. It delegates tasks to Implementor agents in parallel.
5. A Verifier checks the results before you review and merge.

Context

The Context tab is where you see everything an agent draws on in a workspace: the Spec, any notes you add, the MCP servers you’ve connected, and any agents and skills Markdown files Intent detects in your repository. Together these form the shared context every agent works from.

Notes are persistent documents inside your workspace. They’re shared between you and your agents — anything you write, agents can read, and vice versa. Add your own notes to give the workspace more context: reference material, requirements, decisions, or links become shared context every agent works from. Notes render images and video inline, so you can keep visual context next to your text. The most important note is the Spec.

The Spec Note

Every workspace has a Spec note. It’s the planning document — the source of truth for what the workspace is trying to accomplish.

A good Spec includes:

• Goal — the user-visible outcome.
• Tasks — work broken down into trackable blocks.
• Acceptance Criteria — how you know it is done.
• Non-goals — what is explicitly out of scope.

Agents read the Spec before starting work. A clear Spec = better agent output.

Visual Verification

Verification steps can carry visual evidence. Agents embed before-and-after screenshots — saved as ordinary workspace files — directly in the Spec with standard Markdown, and Intent renders them inline (in the Spec, task notes, and chat) with a click-to-zoom lightbox, so you can confirm a change at a glance instead of rebuilding it from a diff.

Creating & Editing Notes

• Open the Context tab in the sidebar (Cmd+Shift+N)
• Click + New Note to create one
• Notes use a Markdown editor with rich formatting
• Add tags to organize notes
• All changes save automatically

Task Blocks

Agents create trackable tasks automatically as they plan — if one doesn’t, just ask it to. Under the hood, tasks are @@@task blocks, which you can also write yourself in any note:

@@@task
# Add user authentication
## Scope
- Login/logout endpoints
- JWT token management
@@@

When you save the note:

1. Each @@@task block converts into a Task Note
2. The block is replaced with a linked checkbox
3. Agents can be assigned to Task Notes and update their status

Rules:

• One task per @@@task block
• The first # Heading becomes the task title
• Everything below is the task body
• Optional attributes on the fence line — key=, dependsOn=, conflictsWith=, effort= — express dependencies and estimates

Task Notes track richer statuses than just to-do and done — in progress, blocked, waiting, review required — and can be delegated to agents directly from the note.

Rich Blocks

Notes support special blocks that make documentation actionable:

Comments

• Highlight text and click Comment
• Agents can comment too — useful for questions or suggestions
• Comments appear as threads anchored to specific text
• Resolve threads when addressed

Comments are great for async collaboration between you and your agents.

MCP Servers

Any MCP servers you’ve connected appear in the Context tab, so you can see which external tools and data sources are available to agents in this workspace. Agents call these tools directly as part of their work. Connect and manage servers in Settings & Configuration.

Agents & Skills Files

Intent automatically scans your repository for agents and skills Markdown files — such as AGENTS.md, CLAUDE.md, and files under a skills/ directory — and, when present, surfaces them in the Context tab. These files are picked up as shared context so agents follow your project’s conventions and use the skills you’ve defined without any extra setup.

Git & Code Changes

The easiest way to handle git is to just talk to your agents and turn on auto-commit — agents commit their own work with descriptive messages as they go, so you rarely have to think about it. If you have a specific workflow or want a more visual way to move through the git process, we’ve built it into the Changes panel. From there you can:

Viewing Changes

Open the Changes tab in the sidebar. It’s a timeline of the branch: file changes at the top, then commits, the pull request, and merging. The file list shows:

• Modified files — Files the agent (or you) changed
• Staged files — Files ready to commit
• Untracked files — New files not yet tracked by git

Committing

Two ways to commit:

1. Agent auto-commit — Agents commit their own work with descriptive messages as they go
2. Manual commit — Open the Commit drawer, stage files, write a message (or auto-generate one with the message button), and commit

From the commits timeline you can also push commits to the remote and undo or amend recent local commits.

Pull Requests

• Create a PR — Intent pre-fills (or auto-generates) the title, description, and target branch
• View PR status — See CI checks, review comments, merge state
• Address review comments — Agents can read and respond to PR feedback, and can monitor a PR in the background to act on comments and CI results
• Merge — Merge directly from Intent when the PR is ready

Merging Locally

The Merge drawer merges the workspace branch back to trunk without a PR, and post-merge actions offer cleanup — like resetting the workspace to trunk.

Commit History

The Changes tab timeline shows commits — local and pushed — alongside the branch’s PR and merge state. Click a commit to open its diff.

Panels & Layout

Intent’s interface is built around a flexible panel system. Split, resize, and rearrange panels to match how you work.

The Main Areas

Splitting Panels

Cmd+\ creates a new column to the right. Drag tabs between panels or drag an edge to resize.

Tabs, Panels & Columns

Terminal

Intent has a built-in terminal so you can run commands without switching apps. It slides down from the top like a quake-style console.

Opening the Terminal

• Ctrl+` — Toggle the terminal overlay
• Cmd+J — Alternate toggle shortcut

Multiple Tabs

Create new terminals with the + button in the terminal overlay.

Scripts

The terminal overlay includes a Scripts sidebar — saved per-workspace build, test, and service commands. Run-once commands execute to completion, while long-running services keep output viewers you can check anytime. Fresh worktrees also get a setup-script banner to bootstrap the checkout.

Agents & Terminals

Agents can run terminal commands as part of their work — installing dependencies, running tests, starting dev servers. You’ll see their terminal output in real time, and URLs printed in the terminal are clickable and open in the browser panel.

Browser Panel

Intent includes a built-in web browser for previewing web applications without leaving the app.

Opening the Browser

• An agent starts a dev server and navigates to it
• You open a URL from agent output or a note
• You manually navigate to a URL in the browser panel

The Browser sidebar tab lists every tab open in the workspace. Tabs opened by agents start hidden — reveal them from the sidebar, or the agent shows them itself.

Dev Server Preview

When an agent runs a dev server, it can automatically open the browser panel to the local URL. As the agent makes changes, you see updates in real time.

Navigation

Back and forward live in the browser toolbar. An element picker in the toolbar lets you point at any element on the page.

Agent Browser Interaction

Agents can take screenshots, inspect the page for layout, accessibility, and console errors, and interact with elements to test functionality. During structured capture runs, Intent records a screenshot, the page’s accessibility tree, and console output at each step, giving agents an archive of visual states to embed as verification evidence. Tabs are tracked per agent — an agent drives its own tabs, and you can always view and take over.

Settings & Configuration

Open Settings with Cmd+,. Settings are organized into these tabs:

AI Providers

In Providers, configure which agent providers agents use and set the default model for new agents. Supported providers are Augment Auggie, Anthropic Claude Code, Grok Build, OpenAI Codex, OpenCode, Pi, and Unsloth. Different specialists may use different models.

MCP Servers

MCP servers give agents access to external tools — databases, APIs, design tools, and more.

• Add servers globally or per workspace
• Each server provides a set of tools agents can call
• Configure in Settings → Connections

Theme, Fonts & Display

• Light / Dark / System theme — follows your OS preference by default
• Chat font style — Choose how agent messages look
• Code font — Pick the monospace font for code blocks and the editor
• Note font — Serif or sans-serif for note content
• All under Settings → Display

Connections

Voice Dictation

Dictate prompts instead of typing — configure local Whisper or ElevenLabs transcription under Settings → Input.

Rules & Skills

Customize how agents behave:

• AGENTS.md — A file in your project root that agents read automatically
• Global instructions — Personal rules applied across all workspaces (Settings → Agent Behavior)
• Skills — Specialized instruction sets agents load for specific tasks

Rules are the best way to get consistently good output from agents — tell them your project’s patterns once, and every agent follows them.

Keyboard Shortcuts

Press Cmd+? (Cmd+Shift+/) to open the full shortcuts reference, searchable, grouped by category, and editable:

• Global
• Workspace Navigation
• Tabs & Panels
• Chat & Agents
• Terminal
• Browser
• Leader Key (Cmd+;)

Rebind any shortcut by capturing a new key combination, and reset a single override or all of them back to the defaults.

Open Source

Intent is licensed under the Apache License 2.0.

Latest Release

v2.129.1. Stable users upgrading from v2.118.0 gain remote-backend connectivity, inline images and video, a rebuilt embedded browser, a smarter model picker, and clearer PR and agent status, all running on a substantially updated daemon.

Headline features

• Connect to remote backends. Dial a remote daemon through a bundled secure tunnel. You can sync your connection address across devices via the keychain, pair with intent://pair deep links, and manage it all from the new Devices and Advanced settings, with graceful per-host certificate handling while reconnecting.
• Images and video in chats and notes. Embed and view images and video inline in both chat and notes, including workspace videos rendered from Markdown.
• Revamped embedded browser. The in-app browser panel now fits the viewport properly and adds an element picker for pointing at things on a page.
• Aurora and translucent window. New settings toggles add the animated aurora chat background and a translucent app window, along with a GPU-cost reduction that keeps it smooth.

Agents, models, and workspaces

• Model picker upgrades. Pick a reasoning-effort level inside the model dropdown, with consistent model selection across agent creation, settings, and specialists. Provider cards now show which email or org account they are connected as.
• Clearer PR and agent status. Each workspace row shows one PR icon for its earliest flow state, a new pr_queued status marks merge-queued PRs, and agent file locks appear in the Changes panel.
• Sidebar and workspace polish. This release refines sidebar workspace actions, surfaces secondary-root changed files, restyles hover cards, and makes keyboard shortcuts editable.

Quality-of-life fixes

• Onboarding. Onboarding now supports non-git local folders, explains why the Create button is disabled, and migrates onboarding images cleanly to context items.
• Chief of Staff. The Chief of Staff can create new threads, with a polished header.
• Networking. This release adds a Local Network Access toggle, a via-tailcat tunnel indicator, reorganized WebSocket API settings, and full TLS fingerprint display.
• Performance. Style recalculation is reduced, renderer churn is bounded, and scrollback fetching is smarter during rapid scrolling.

Under the hood

The daemon moves from intentd 0.8.29 to 0.9.12: daemon-owned agent lock state over the protocol, per-workspace MCP server disable, PR-aware checkout (head plus base-branch merge target), the tunnel sidecar, a model-triple resolution overhaul, note.saveAsset exposed to agents, hardened secrets storage, and numerous auth and merge-queue reliability fixes.

Release History

Previous Intent releases and their notes.