AM Stellar

Lightweight VS Code coordination for parallel coding agents, from RBoyle Software.

Stellar makes it easy to tell which of several Claude Code, Codex, Qwen Code or other coding agents is doing what, and to switch your attention between them. It observes and doesn't take over: your editor, CLI agents, Git workflow and Linear stay as they are.

Preview. Stellar is used every day with Claude Code. Codex and Qwen Code support hasn't been fully tested yet (see Supported agents). Expect changes before 1.0.

Feedback

Bugs, ideas and questions: use the feedback form, or run Stellar: Send Feedback… (also in the Agents view's ⋯ menu), which fills in your Stellar and VS Code versions and OS. Feedback goes to the people building Stellar.

Requirements

• VS Code 1.138 or later.
• Git. Stellar gives each agent its own branch and worktree.
• At least one agent CLI on your PATH: claude (Claude Code), codex (Codex) or qwen (Qwen Code). Stellar starts and resumes them; it doesn't install them, sign you in or hold their API keys.
• A terminal shell with VS Code shell integration: bash, zsh, fish, pwsh or Git Bash. Without it Stellar can't tell whether an agent is working (see How state is detected).
• Optional: a Linear personal API key, to pick issues from Linear.

Privacy

• No telemetry. Stellar sends nothing about you or your use of it anywhere.
• Network: only to Linear's API (api.linear.app), and only after you connect a Linear key. Stellar only reads issues.
• Your Linear key is kept in VS Code's secret storage on your machine.
• What Stellar writes: its agent list in VS Code's workspace storage, and the files under .git/stellar/ described below. It never commits or pushes.

Features

• Agents view. A compact list of named agent sessions. It lives in one of two places. The → button in its title bar moves it to the other, and the am-stellar.viewLocation setting chooses too:

  • explorer (default): a Stellar Agents section in the Explorer, above or below the file tree. Drag the section header to reorder it.
  • activityBar: its own Stellar icon in the activity bar. Here the agents are cards, not a list (see below).

  In the Explorer, each row shows:

  • state: active (producing output), idle (quiet, and may be waiting on you), unknown (Stellar can't see its output; the row's Restart button restarts the agent) or lost (its terminal or agent process is gone; the row's Resume button resumes it)
  • agent name, a persistent, human-readable given name (star names by default)
  • issue ID, when assigned: any format your team uses, such as ARC-245, PROJ-12 or #123
  • agent type (Claude Code, Codex, Qwen Code, Other)
  • branch, plus the worktree folder when the agent works in a linked worktree
  • at most one badge on the right, like Git's status letters: 🔵 for the agent whose terminal is in front, otherwise 👀 for the agent you're following, otherwise 🔴 for an idle agent. Turn badges off with am-stellar.badges.enabled, or change or empty one with am-stellar.badges.focused, .followed and .idle

  In its own activity bar frame, Stellar has the whole side bar, so each agent gets a card in the colour of its terminal tab:

  • What a card shows: a top row with the name in capitals, the agent type, the issue ID and the state (a lamp: the word beside an LED that pulses while the agent is active, glows steady while it is idle, is out when it is lost and is an empty socket when it is unknown); then the issue title, and the branch and worktree. In a narrow card the top row drops the agent type and shows the state as the LED alone. The card of the agent whose terminal is in front is tinted in its colour, and the one you're following has Unfollow.
  • It uses the room there is: a full card each for up to 5 agents, two lines each for 6 to 15, and one line each beyond that.
  • Click a card to bring that agent's terminal forward, or to resume it if it is lost. Focus, Follow or Unfollow, Resume, and Assign issue for an agent without one are buttons on the card; with more than 5 agents they appear when you point at or focus a card.
  • Everything else (rename, assign an issue, set the worktree, mirror, release, remove) is in the card's right-click menu, which its ⋯ button also opens.
  • Keyboard: Tab to a card, ↑ and ↓ to move between cards, Enter to focus the agent.
  • The top stays put: how many agents are active, idle and lost, New agent and Attach terminal, and what you're following, with Refresh and Unfollow. The cards scroll under it. When every agent is lost or unknown, as after an editor restart, Resume all takes the first place, next to New agent; Attach Running Agent Terminal is still in the view's ⋯ menu.
  • It never scrolls sideways: each card shows the agent's name in a pill of its colour. At its narrowest, a card is the agent's initial in a circle of that colour, a state light and icon buttons, and the whole card opens when you point at or focus it. That card can be no wider than the side bar, so its lines wrap.
  • Updates in place: the view changes when an agent does (checked every second; branches every 10 seconds), and only the card that changed is redrawn.

• Focus. Click an agent, or use Focus Agent, to bring its terminal forward. Focus never runs a checkout or otherwise changes your Git context.

• Terminal binding. Each session owns a terminal named and colored after the agent. Sessions re-bind to their terminals after a window reload. After an editor restart, VS Code restores the terminal tabs but not the agents in them, so those agents show as lost until you Resume them in the same tab. If Stellar doesn't match a tab, or you restarted an agent by hand, Connect to Terminal… on the agent's row binds it to an open terminal.

• Lost sessions are kept. When an agent exits or its terminal closes, the session stays in the list so you can Resume or Remove it. A missing terminal never removes an agent, and Stellar never deletes a worktree or branch on its own.

• Agents are found again from the registry. When you open a workspace, Stellar reads the registry of each repository in it and shows every agent registered there, with or without a terminal: after a restart, after switching between a local build and the Marketplace build, or when another window that tracked them has closed. Agents another open VS Code window tracks stay with that window.

• One agent per worktree. Attach Running Agent Terminal in a worktree that already has an agent attaches to that agent instead of registering a second one; when it can't tell which agent it is, it asks. Copies of one agent registered under the same name for the same worktree are merged; differently named agents in one worktree are shown to you to choose from.

• A missing worktree keeps the agent, marked Worktree missing. Resume explains instead of starting it somewhere else; Set Agent Worktree… points it at its folder again.

Every agent in its own worktree

New Agent Session creates a fresh branch and worktree for the agent by default. That way Stellar always knows where the agent works, Follow always has something to follow, and no agent edits your checkout.

• Branch: prefilled with Linear's branch name when you picked the issue from Linear, which keeps the branch linked to the issue. Otherwise arc-301-vega (issue + name) or agent/vega. Always editable. New branches start from main (or am-stellar.follow.baseBranch). An existing branch is checked out as-is.

• Location: <repo>.worktrees/<branch> next to your checkout, outside it, so dev servers, file watchers and search never see agent worktrees. Change it with am-stellar.worktree.root, e.g. .claude/worktrees.

• Not copied: ignored files such as node_modules and .env. The agent installs what it needs.

• Remove Agent… offers to delete a worktree Stellar created. The branch is kept, and a worktree with uncommitted changes is never deleted.

• Checked before it is created: the form tells you if the branch name isn't valid, if another worktree already has the branch checked out, or if the worktree's folder already exists, while you can still change it.

• To make existing worktrees the default, turn off am-stellar.newSession.createWorktree. "New worktree" then moves to the bottom of the list.

• Coding agent: the form preselects the one you started last, in any workspace. To always start from the same one, set am-stellar.newSession.agent.

Agent names are random picks from 60 stars. Stellar avoids names used recently in the workspace and prefers first letters no active agent has.

Pick the issue from Linear

New Agent Session is one form in Stellar's side bar frame, and it starts with the work: pick an issue, then name the agent, choose its type and its worktree. Assign Issue and Attach Running Agent Terminal… use the same form, with only the fields they need.

• Keyboard: the issue search has the focus. Type, use ↑ and ↓ to move through the list, and press Enter to pick the issue, which moves on to the name. Enter there starts the agent. Esc cancels. In Assign Issue, picking an issue assigns it at once.

• Connect once: run Stellar: Connect to Linear… (or pick Connect to Linear… in the form) and paste a personal API key from Linear: Settings → Security & access → Personal API keys. Stellar checks the key with Linear before saving it.

• Where the key lives: in VS Code's secret storage on this machine, never in settings or the repository. Stellar: Disconnect from Linear deletes it.

• Read-only: Stellar only reads issues. It doesn't change issues, states, assignees or comments.

• What's listed: open issues (Triage, Backlog, Todo and In Progress types), in groups:

  1. Recent: issues you picked in this workspace
  2. Assigned to you: in progress first
  3. Labelled agent-ready: change the label with am-stellar.linear.readyLabel, or empty it to hide the group
  4. Other open issues

• Search: typing narrows the list and also searches Linear, so issues beyond the first 100 show up under Search results. Typing an ID such as ARC-301 finds that issue directly, and so does the bare number, 301: Stellar looks it up in each of your workspace's teams (up to 10).

• Any tracker: whatever you type can be used as the issue ID (Use "…"), so Jira keys, #123 and the like still work, with or without Linear. No issue is always there too.

• What the agent gets: for a Linear issue, the agent's briefing, the registry and the row's tooltip include the issue's title and link, and the worktree's branch defaults to Linear's branch name.

Agents know who they are: the shared registry and startup briefing

Stellar keeps a registry of the agents it tracks, and starts each new agent with a short briefing that tells it its name, its assignment, and where the registry is.

• What's in the registry: each agent's name, agent type, issue (with its title and link when picked from Linear), worktree root, branch, state (active / idle / unknown / lost) and, when known, the provider's own session id. Stellar rewrites it whenever any of these change. Agents only read it.
• How an agent finds itself: it matches its working root (git rev-parse --show-toplevel) against agents[].worktree. The provider session id is supplemental: not every agent type has one.
• Several windows: each VS Code window replaces only the agents it tracks, so windows open on the same repository share one registry. Each window also notes, every minute, that it is still open. When a window has been closed for a few minutes, the next window to open the repository takes over its agents. Windows take turns writing, with a lock file, so none overwrites another's changes.
• Startup briefing: New Agent Session starts Claude Code with the whole briefing as its first prompt, so the command in the agent's terminal shows everything the agent was told. The briefing gives the agent its name and initial assignment and tells it to treat the registry as the source of truth from then on. It names no absolute paths: the registry is stellar/stellar-registry.json in the folder git rev-parse --git-common-dir prints. With an issue assigned, the briefing tells the agent to review the issue, then ask you if it needs a decision or clarification, or else start work. With no issue, it tells the agent to confirm who it is and wait for you. Codex and Qwen Code are started the same way, but neither has been fully tested yet (see Supported agents). Turn this off with am-stellar.briefing.enabled.
• Exact resume for Claude Code: Stellar starts Claude Code with its own --session-id, so Resume runs claude --resume <id> and reopens that agent's conversation, not just the most recent one in the folder.
• Agents you attach were already running, so they get no briefing, but they still appear in the registry.

Separation of concerns: the registry is local coordination truth, the briefing is a one-time briefing, the Agents view and terminal tab are presentation, Linear holds shared task state, and Git holds the code.

Where Stellar keeps its files

Everything Stellar writes for a repository lives in one folder, .git/stellar/, inside the repository's common Git directory:

• Why there: the main checkout and every linked worktree resolve the same folder with git rev-parse --git-common-dir, so every agent finds the same registry without relative paths.
• It's hidden: VS Code hides .git from the Explorer by default, and nothing in .git is committed, pushed, or seen by dev servers, file watchers or search. To look at the registry, run Stellar: Open Agent Registry.
• Moved in 0.1.19: the registry was agents.json. The first time 0.1.19 or later writes it, every agent is carried over with its id, name, issue, worktree and branch, the old file is kept as agents.v1-backup.json, and agents.json stays as a copy. An older build still running in another window keeps working: what it writes to agents.json is brought in, and Stellar tells you if it is tracking an agent a newer window has taken over.
• If the registry can't be read, Stellar sets it aside as stellar-registry.unreadable-<time>.json, tells you, and writes a new one from the agents it knows. It never overwrites a file it couldn't read.
• Safe to delete: Stellar recreates the registry on its next change, but agents no window is tracking are then forgotten. Deleting patches/ loses only the backup copies.
• Contents: names, issue IDs, paths, branches and session ids. No source code, credentials or conversation content.

Agent permissions

An agent's worktree doesn't contain .git/stellar, so agents would normally need permission to read outside their working folder. Stellar doesn't ask you to change your agents' permissions. Instead:

• Claude Code: Stellar passes --add-dir <repo>/.git/stellar when it starts or resumes an agent. That grants read access to that one folder, for that one session. Your settings stay as they are. (If you had already allowed Claude Code to read outside the working directory, you can take that back.)
• Codex: not yet fully tested. Stellar gives Codex no extra access, and it isn't yet known whether Codex can read .git/stellar from a worktree.
• Qwen Code: Stellar passes --include-directories <repo>/.git/stellar in the same way. Run non-interactively from a worktree, Qwen Code 0.25.0 read the registry with or without the flag. Whether it asks first in an interactive session hasn't been tested.
• Agents started outside Stellar (Attach Running Agent Terminal, or claude --continue on Resume) don't get the flag, and may ask before reading the registry.

Supported agents

Stellar starts agents through their command-line interfaces. It relies on a few CLI flags, and an agent update could rename or remove them.

Codex and Qwen Code have not yet been fully tested. Claude Code is the agent Stellar is developed and used with every day. Expect rough edges with the other two, and check the notes in the table.

Staying current:

• Checked at launch. Before using an optional flag, Stellar checks that the installed agent's --help still lists it, once per window. A missing flag is left out, with a one-time warning naming the version Stellar was tested with, so the agent still starts.

Follow: review and test an agent's work in your own checkout

Follow brings an agent's work into your checkout, in the same window where your dev servers are running and your ignored files (node_modules, .env, caches) already exist. You can then review it in Source Control and test it in the running app, while the agent keeps working undisturbed.

• Follow Agent (Branch Preview), the 👁 on a row: switches your checkout to the reusable stellar/follow branch at the point where the agent's branch split from main. Everything the agent has done (commits plus staged, unstaged and new files) appears as uncommitted changes.
• Add Agent to Preview: layers another agent's work on top. Where agents touched the same lines, you get conflict markers: an early warning that they'll collide.
• Mirror Agent (Exact): shows exactly what the agent has. It uses the agent's own commit and the same staged / unstaged / untracked split.
• Refresh Preview: takes a fresh snapshot while the agent keeps working.
• Unfollow (Back to My Work): returns you to your branch and restores your uncommitted work.

Agents that move into their own worktree. Claude Code can start in your checkout and then create its own worktree (for example .claude/worktrees/angular-starter). Stellar only sees where the agent's terminal started. So when you Follow an agent that's registered in your checkout, Stellar asks which worktree it's working in and remembers the answer. You can also correct it any time with Set Agent Worktree… on the agent's row.

What stays safe:

• Agents are read, never written. Stellar snapshots an agent through a temporary copy of its Git index. The only exception is when you choose to apply your edits to an agent as a patch.
• Your uncommitted work is stashed before the first Follow and restored on Unfollow.
• If Follow fails, it undoes itself: your checkout goes back to the branch and uncommitted work it had, or to the preview it was showing. The error says which. If Stellar can't put it back, the error says so, and Unfollow stays available to try again.
• Ignored files are never touched. Neither are other worktrees nested inside your checkout, such as .claude/worktrees/*.
• If you leave a preview by hand, for example with git checkout in a terminal, Stellar stops following the next time you use Follow or reload the window. It doesn't reset or change your files. Work it stashed before following stays in git stash list.
• Edits you make while following: on Refresh, Unfollow or switching agents, Stellar asks whether to discard them or apply them to an agent as a patch. A copy is always saved under .git/stellar/patches/.
• Stellar never runs installs or migrations. It warns when a preview changes paths listed in am-stellar.follow.warnPaths, such as lockfiles, package.json and **/migrations/**.
• Follow refuses to start while your checkout is in the middle of a merge, rebase or cherry-pick.

Settings: am-stellar.follow.baseBranch (default: main, then master, then origin/HEAD) and am-stellar.follow.warnPaths.

Commands

On macOS, use Cmd in place of Ctrl.

How state is detected

• Lost: the session's terminal was closed, or the agent's own command (claude, codex, qwen) exited back to the shell.
• Active / idle: based on whether the terminal has produced output in the last 4 seconds.
• Unknown: the terminal is there and the agent hasn't exited, but Stellar isn't reading its output, so it can't tell working from waiting. Stellar can only read the output of a command it saw start. A window reload keeps the agents running but starts Stellar afresh, so every agent that was running shows as unknown afterwards. Restart Agent closes the terminal and resumes the agent in a new one.

Both rely on VS Code shell integration, which works with bash, zsh, fish, pwsh and Git Bash. In shells without it, such as cmd.exe, agents always show as unknown until their terminal closes, and restarting them doesn't change that.

Sessions are stored per workspace in VS Code's local extension storage. Detecting state writes nothing to Linear or Git.

Which build is running

The Agents view header shows the version, e.g. v0.1.1, and in the activity bar the cards show it beside the agent count. Stellar: About Stellar shows it too and can copy it. Local builds add the commit they were built from, e.g. v0.1.1 dev gb0c0c46, and dirty when built with uncommitted changes. package.json is never changed by a local build.