Skip to main content
In Orchestra Local, your memories and sessions stay on your laptop until you choose to share them. Shared, they travel through the repo’s own git remote: your teammates’ agents get your memories when they work on something related, and when a memory cites the session it came from, a teammate can open that session, with its diffs. Nothing goes through an Orchestra server: pushes and fetches use your own git credentials, against the same host your code lives on. Sharing sessions is free on every plan, so anyone on the team can open the session behind a commit. Sharing memories and issues is part of the Team plan (see The Team plan). On your own, Orchestra Local is free, with a free account. Issues work the same way on Orchestra Local: the issues you and your agents create, with their comments, status, assignee, labels, project and parent, travel through the same git remote, so the whole team sees them without switching to the hosted workspace. See Issues below.

How it works

  1. Shared by default. Every repo you turn on with orchestra enable --local shares your finished sessions and their memories with everyone who can read the repo, on every plan. At a terminal, setup asks once per repo, with yes as the default; the desktop app shows a switch that starts on. Without a terminal (a script, an agent, the desktop app’s own setup) nothing is asked and the repo shares, and setup says so. Say no for a repo, or make one session private, and that work stays on your computer.
  2. Sharing is automatic. When a session ends, it and its memories are redacted, checked for secrets, and pushed in the background with your git credentials. Your session is never held up by a push. Memories written from a session shortly after it ends follow it on their own, as soon as they are written. A private session is never published, and neither are its memories.
  3. Every agent’s sessions publish on their own. A Claude Code session publishes when it ends. So does a Codex session, once Codex trusts the hooks orchestra enable wrote in .codex/hooks.json (run /hooks in Codex once and trust them; Codex asks again after enable changes them). Until you do, Codex sessions in the repo get no teammate memories, and they publish a few minutes after they go quiet instead of when they end. Gemini CLI, Cursor and OpenCode have no hook that marks a session’s end, so their sessions publish a few minutes after they go quiet, and again after each later stretch of work. orchestra session publish <id> publishes one right away. A Claude Code or Codex session can also end without its end hook running: the terminal is killed, the agent crashes, or the computer sleeps or shuts down. Orchestra then marks it ended and publishes it for you, as soon as it sees the agent’s process is gone, or after 30 minutes with nothing written when it cannot tell. Teammates stop seeing it as live at the same moment. A private session is marked ended but never published. If you go back to the session, it carries on as the same session and is published again when it next ends.
  4. Teammates read only what they need. Every laptop keeps a small index of who shared what. When an agent starts a task, Orchestra picks the few shared memories that bear on it, fetches just those, and gives them to the agent with whose they are and which session they came from. Opening that session fetches that one session and nothing else. Nobody’s laptop holds everyone’s sessions or memories. Claude Code is handed them with the prompt that starts a task; so is Codex, through its prompt hook.

The one question, and what each answer changes

Sharing is on unless someone turned it off. Four things can turn it off for a repo, and each one always wins:
  • Your no, kept on your laptop: orchestra session consent no in the repo (or orchestra enable --local --share no). Each teammate answers for their own sessions. orchestra session consent yes shares again.
Your explicit yes adds one thing the default does not: teammates’ agents can ask your laptop about the repo (see When a teammate’s agent asks yours).
  • A team admin’s off, in the team’s policy: orchestra team sharing off (below).
  • The team’s file: auto = false under [share] in .orchestra/config.toml, committed for everyone.
  • Personal: a repository in Personal is never shared.
A private session is never published, whatever the repo says: start it private (ctrl+p in the terminal client, or orchestra start --private), or make it private later (orchestra session private <id>, or Make private on a session row in the desktop app).

Is this repo publishing my work?

One answer, and every place says the same: orchestra local status (a line per repository), orchestra doctor, orchestra team sharing, orchestra team status, the terminal, and People in the desktop app. When a repo does not publish your sessions, each says why and the one command that changes it.

Sessions that ended before you said yes

When you say yes after a no (or on a laptop set up before sharing became the default, where nothing was published), Orchestra offers the sessions of yours that ended in that repo while nothing went out:
Only your own, ended sessions in that repo, since it was turned on here, are published, each through the same redaction and secret check. A private session, or one you unpublished by hand, is never published this way.

What a yes writes

A yes at setup also writes the team’s half, auto = true under [share] in .orchestra/config.toml (sharing is on without it; the line records the choice in the repo):
  • Setup writes it and offers to commit it for you: that one file, on the branch you are on, with the message “Turn on Orchestra sharing in this repo”. Push it with your next change, so the choice is in the repo and reviewed like any other change to how the team works. It is the one file of Orchestra’s to commit: the hook files enable writes hold your laptop’s setup, so they are listed in .git/info/exclude and git add -A leaves them out.
At a terminal, setup says what it will commit and asks first; yes is the default. Say no and it leaves the file for you, with the command to commit it:
Without a terminal (a script, or the desktop app’s Setup), it commits and says so, with how to undo it: git reset --soft HEAD~1, while that commit is still your latest. --no-commit-config leaves the file for you to commit instead. Commit it either way. When two teammates both turn sharing on before either has pushed, each has the file committed, and git merges the two copies like any other change, so neither one’s git switch or git pull stops on it. Until it is committed, a teammate’s committed copy stops git switch and git pull in your clone. Setup also leaves the file uncommitted, and says why, when it cannot commit it cleanly: you are not on a branch, a merge or rebase is under way, the file already held edits of yours, or a commit hook refused. When your laptop is signed in to an Orchestra team, every repo you turn sharing on in is shared with the team, with no step from an admin. A team admin can turn sharing off for one repo:
While it is off, nothing from that repo is published on its own, and setup, orchestra doctor and the terminal say who turned it off and when. Sessions that ended meanwhile are kept, and go on their own once it is back on. orchestra session publish <id> still publishes one session by hand. A public repo and a private session are never published, whatever the policy says. Signed in to an Orchestra team, your agents can also reach teammates live: the team map, asking a teammate’s agent, joining and steering a session, agent messages and collision warnings. These team features are part of the Team plan too.

Your Local team

A team on Local is its own team in Orchestra, separate from any hosted workspace you sign in with. It holds who is on the team, their laptops’ keys for the live features, and the team’s plan. It never holds your work: sessions, memories and issues still go only through your repo’s git. The step-by-step guide for starting a team and for each teammate joining it, in the desktop app, is Working as a team on Local. From a terminal, make one, with you as its admin, and invite people by email:
Each person you invite gets an email from Orchestra with a link to join. Once they join and sign in on Local (orchestra login), their laptop finds the team on its own within a minute and joins its live features. Nobody types the team’s name. As the admin you can rename it with orchestra team rename <name>; everyone sees the new name. orchestra team invitations lists who has not joined yet (only the admin can see it), and orchestra team revoke <id> withdraws an invitation. If you are on more than one Local team, orchestra team teams lists them and orchestra team use <name> chooses the one this laptop uses. To rename, invite to or manage invitations for another of your teams without changing that, add --team <org id> (for example orchestra team invite --team org_123 teammate@example.com). Your hosted workspace, if you have one, is unchanged by any of this.

Workspaces on your computer

On Local, your computer keeps a workspace for each Local team you work with, plus Personal, which is just you. They work like workspaces on Cloud: each one has its own sessions, memories and issues, and nothing in one shows up in another. Everything you had before you joined a team is in Personal. A repository can belong to one or several of them. When you turn Orchestra on in a repository and you are on a Local team, you are asked which one. You can choose, add more, or change it later:
--workspace can be repeated, or take a list (--workspace "Night Shift, personal"). orchestra workspaces add <name> puts the repository you are in in one more workspace, and orchestra workspaces remove <name> takes it out of one. orchestra workspaces use <name> makes that workspace the only one. Each command says what changes: new sessions in the repository go to every workspace it belongs to, sessions saved before stay where they are, and nothing is copied. That includes a session already running when you add a workspace: it stays out of the new one, and the next session goes to both. A repository always saves somewhere, so removing its last workspace is refused; move it with use instead.

Several workspaces for one repository

Every session in a repository goes to every workspace the repository belongs to. Each workspace keeps its own copy, as if the session had been saved there alone, and each team shares its copy with its own teammates exactly as it does for a repository on that team only: live sessions over the relay, sessions and memories through git, and issue sync. If Personal is one of the workspaces, the copy in Personal is never shared, through git or any other way. Memories you write with remember (or an agent writes in the repository) go to every workspace too. A memory that replaces an earlier one stays in the repository’s first team workspace, because each workspace’s copy of the earlier memory has its own id. Issues you create in the repository go to its first team workspace only (Personal when it is on no team): an issue copied into two workspaces would get two keys and drift apart. A team that moves its repositories to its hosted workspace moves only the repositories that are on that team alone. One that is also in Personal or another team keeps saving to each of them on your computer. An older version of Orchestra on the same computer reads only each repository’s first team workspace (or Personal when it is on no team), so it saves there and nowhere else. Update it to save to all of them.

Before the first choice

Until you choose a workspace for a repository, your computer is one workspace, as before: your work on Local is shared with your chosen Local team (orchestra team use <name>), and there is no Personal yet. A new Local team is empty until a repository is added to it. At a terminal, enable offers “Not now” first, and Enter takes it, so nothing changes until you choose. The first choice on a computer changes this for good, whether it is made with enable --workspace, workspaces use or workspaces add. Personal appears with the work already on your computer. The repositories you already turned on for Local move to the team you shared with, and their sessions from the last 30 days are copied there. Nothing else moves. From then on each team sees only its own workspace, and Personal is never shared. When orchestra workspaces use moves a repository to a team, its sessions from the last 30 days are copied into the team’s workspace from the session files on your computer. New sessions go there from then on. Within a minute, Personal stops listing the copies that now live in the team, so each session shows in one workspace. Nothing is deleted: put the repository back in Personal and Personal lists them again. A repository that is in Personal and a team shows its sessions in both.

Seeing and changing them

orchestra workspaces lists your workspaces and the repositories in each. Inside a repository it starts with where that repository saves (“app saves to Personal and Night Shift on this computer.”) and marks each of its workspaces with >. In the terminal client, home names the repository’s workspaces beside the folder, and ctrl+o (or /workspace) lists them with each one the repository belongs to ticked: Enter adds the highlighted workspace or takes a ticked one off, without quitting (see Choosing the repository’s workspace). A repository you have never chosen for starts on a suggestion: the workspace your other repositories with the same remote owner use on this computer, else the one you chose last. Once you choose, you are not asked again. In the desktop app, the workspace menu lists your workspaces under Local, and the whole window then shows only the one you choose. Repositories on this computer, in the same menu and in Settings, This machine, lists each repository with a checkbox for each workspace (see Switching workspaces).

The Team plan

Sessions are free on every plan. Publishing a session to the repo’s git, listing your teammates’ sessions and opening one (from a commit, a pull request, orchestra why or the list) need no plan. Sharing memories and issues through git, forking a teammate’s session, and the live features above need the Team plan. The plan is your Local team’s. Your laptop reads it when you sign in (orchestra login), so they work once you are signed in and on a Local team on Team. Without it (signed out, on Free, or after a Team plan ends), capture, recall, your own memories and shared sessions are unchanged. No memory or issue is published, and none is fetched from teammates. Setup, orchestra enable, orchestra doctor and the desktop app say so in one sentence: “Sharing memories and issues with a team needs the Team plan, so they stay on this laptop and none are published or fetched (sessions are still shared on every plan).” After a trial or a Team plan ends, shared memory is read-only: your laptop still fetches what your team already shared (at session start, in recall and in search), and only publishing something new waits for a plan. What you already shared stays in git as it is, and you can still take it back with orchestra memory unpublish, orchestra memory leave or orchestra session unpublish. When your laptop cannot reach Orchestra, it uses the plan it last saw for up to seven days, then works alone until Orchestra answers again. A laptop that has never read a plan works alone. To get the Team plan, see Pricing. To answer without the prompt (a script, or a terminal that cannot ask):
With no --share, the repo shares by default. --share no (or orchestra session consent no) keeps your sessions in this repo on your laptop. You can still publish one session by hand. Add --no-commit-config to a yes to commit .orchestra/config.toml yourself.

The team key

Shared memory needs a team key. The key lets each laptop search the index without the index spelling out what memories say. Nobody has to make one:
  • The first person to share a memory in a repo gets a key made on their laptop. Git holds only its id and a check value, at refs/orchestra/team-key, never the key itself.
  • Teammates’ laptops receive the key from a teammate’s laptop that is online, device to device and end to end encrypted. Each laptop checks what it receives against git before keeping it. Someone who joins later gets it the same way.
  • Until a laptop holds the key, its memories wait and teammates’ memories are not searched. orchestra doctor and the terminal’s Memory view say so, and say what to run.
  • Keys stay inside their team. If you are on more than one Local team, your laptop keeps each key with the team of the repository it belongs to, and hands it only to that team’s laptops. Someone on your other team who learns a key’s name from a repository’s git gets nothing from your laptop.
  • When someone leaves the team, the key changes. See When someone leaves.
Shared issues use the same key, so a laptop that holds it reads teammates’ memories, sessions and issues alike. For two laptops that are never online at the same time, hand the key over by hand. On a laptop that holds it, in the repo:
It prints the key once, with a warning: anyone who holds it can read what your team shares in this repo, if they can also read the repo. Hand it over in person or through a password manager, never in chat, email, an issue or git. On the other laptop, in the same repo:
and paste it. The key is checked against the id and check value in git before it is kept, so a key copied wrong is refused. Nothing else needs setting. Once the key is on a laptop, key add shows what the team has already shared in the repo you run it in, each with whose it is. To pick a key yourself instead, make one, add it on each laptop and name it in .orchestra/config.toml as below:
A key you name in .orchestra/config.toml wins over the one in git. It never changes on its own: when someone leaves, you replace it yourself, and orchestra doctor reminds you to. To name or rotate the key yourself, add its id to .orchestra/config.toml in the repo, and merge it in a pull request like any other change to how the team works:
[capture] never is for data that must stay on a machine, such as human-subjects data or a licensed dataset. Patterns read like .gitignore lines. When a tool call names a matching path, Orchestra keeps the call and drops what came back: the contents of a file that was read, what a write or an edit carried, a file’s diff, and the output of a shell command that names the path (the command keeps its first line only). It happens before anything is stored, read for memories or shared, and a repository with this rule keeps no raw transcript archive. Each withheld call records which rule withheld it. A path is compared as your computer sees it: src/../data/raw/x, a path relative to where the command ran, a link to the folder, and, on macOS and Windows, any spelling of its case all fall under the rule. What the rule does not cover:
  • A command that reaches the data without naming its path, such as cd data/raw && head *, a script that opens the file, or a variable.
  • A tool that names no path at all, such as a database query through an MCP server or a web fetch.
  • What the agent then writes about the data in its own words.
  • The agent’s own model, which already saw what the agent read. For protected data, use a model you run yourself, or do not point an agent at it.
The rule is read from the file in your working copy, so it applies the moment you write it and follows the branch you have checked out. Anyone who can edit that file on a computer changes what is captured there. orchestra doctor shows the rule in force and says when it differs from the committed one. If the file cannot be read, nothing any tool takes in or returns is captured from that repository until it is fixed. A laptop on an older version of Orchestra ignores the rule, so update every member before relying on it. orchestra memory hosts checks that your git host supports everything shared memory needs (see the host matrix below).

Publish

After a yes at setup there is nothing to run: each ended session’s memories publish with it. Teams that want to read every memory before it leaves a laptop set review = true under [share], and then memories wait for:
This shows every memory you marked shareable, exactly as it will be pushed, and sends nothing. Read it, then:
That pushes exactly what you reviewed. In the terminal, press p in the Memory screen to see the same review, then enter to push or esc to cancel. Before anything is pushed:
  • Redaction removes secrets and personal details (emails, phone numbers) using the same engine as capture, plus your team’s rule packs in .orchestra/redactors. The review shows the redacted text. It catches known key formats, long random tokens, password=... style settings, passwords in connection strings, and credentials written in a sentence (“the db password is hunter2-x9”, “use token abc123def456”). A password that is a plain word with no digit or symbol, written without quotes, is not recognized: put it in quotes, or better, keep it out of the prompt.
  • A secret check runs again on the exact bytes about to be pushed, with every secret detector on, whatever your redaction settings turned off. If it finds anything that looks like a secret (in an edit you made during review, or in a session’s tool output), the push is blocked and nothing is sent. The repo’s own name is never taken for a secret.
  • Public repos are refused. Anyone can read a public repo, so publishing from one is refused unless the team sets allow_public = true. The check asks your git host anonymously whether the repo is readable without signing in; if the host does not answer, publishing waits until it does.
  • A folder other people on the computer can read is refused. When the repo’s remote is a folder on the same computer (a lab server’s /srv/git, say), other people have accounts there, and they can read that folder, they could read what you share. Publishing is refused until the folder is closed to them or the team sets allow_local_readers = true. A computer with one account is never refused for this.
  • Before a private repo is made public. What was already shared stays in the repo and would become public with it. orchestra team shared lists everything shared there, from everyone, and says who can read it; orchestra team shared remove --yes takes all of it off the remote. Nothing on anyone’s own computer is deleted. The host may keep deleted objects for a while, and a fork, a mirror or a teammate’s computer that already fetched keeps its copy.
Each publish is recorded in your own log, so you can always see what you shared, where, and when.

When the automatic publish holds something back

The publish after a session ends runs in the background, so when it cannot send something it says so where you look, not only in its log:
  • A memory the secret check stops is held back on its own, and the session’s other memories still go. orchestra memory shared, orchestra doctor, orchestra status and the terminal’s home all say how many were held, in which repo, and the memory id. orchestra memory publish <id> shows exactly what would be pushed. If it was a real secret, rotate it and forget the memory.
  • A publish that fails because git was busy (another Orchestra process on the same repo, a ref lock) is tried again a few times in the same run, then again after 30 seconds, 2 minutes and 10 minutes, without waiting for your next session. Until it gets through, doctor says when it failed and why.
  • ~/.orchestra/local/share/publish.log keeps every line, each with its time.

Find a teammate’s memory

Your agent gets teammates’ memories when they bear on its task. You can look too: orchestra recall <question> searches your own memory and then the memories teammates shared in this repo, each attributed to whoever shared it. A teammate’s memory cites events in their own log, on their laptop. To read one, follow it the same way as any citation:
Orchestra finds the shared memory that cites it and reads the event from the teammate’s published session, with your git credentials. If that session is not published, it says so and names the session. Agents do the same with the recall tool and an eventId.

When a teammate’s agent asks yours

When recall and the published memory have nothing, an agent can ask a teammate’s laptop directly with the ask_team tool. The question travels end to end encrypted to that teammate’s laptops that are online, and each one decides at that moment what to answer. The answer is the events behind the answer, each one a citation, and nothing is stored on Orchestra’s servers. By default your laptop answers only from repos you said yes to: turned on here, with your explicit yes (orchestra session consent yes, the desktop app’s switch, or yes at setup), and a team file that does not turn sharing off (auto = false under [share]). Sessions and issues share through git by default, but teammates’ agents can ask about a repo only after your yes: until then your laptop answers nothing from it, and orchestra local status, orchestra team status and orchestra team share list name those repos. In a Local team with its own workspace, the repo must also belong to that team. It never answers from:
  • a private session (see Session privacy),
  • a repo a team admin turned sharing off for, or a repo with no remote,
  • a repo in Personal,
  • anything at all while your laptop has no current team policy (signed out, removed from the team, or offline past the grace period).
An answer can include memories you have not published yet, from those repos: ones waiting for your review, or from a session that has not ended. To see, widen, narrow or stop it:
Both laptops keep a record of every question: who asked, the question, and the ids of the events sent back, never the events themselves. It stays in ~/.orchestra/local/team/ on each laptop. A question needs an answer now, so it goes only to laptops that are online. A message your agent sends a teammate’s agent with message_teammate is different: if none of their devices is online, your laptop keeps it and delivers it when one is back, for up to a day. See Messaging a teammate’s session when their laptop is offline.

Sessions

A memory names the session it came from. With sessions shared, a teammate who gets your memory can open that session: the prompts, the agent’s replies, the tool calls, and the diffs, in the same view as their own sessions.

What is published

Each session is a folder in your own ref, refs/orchestra/sessions/<your id>, beside your memories and never in branch history:
  • metadata.json: when it ran, which agent, which files it touched, its title, and what was left out.
  • events.jsonl: the session as Orchestra recorded it, redacted. Teammates’ messages in your session are left out; they are theirs to share.
  • out/: large tool outputs, each stored once and fetched only when someone opens the session.
Paths are written relative to the repository, so they never name your user account or how your folders are laid out: a file reads src/app.ts and the folder the session ran in reads ., never /Users/you/..., /home/you/... or C:\Users\you\.... A folder outside the repository is left out, and any other path in your home folder reads ~/.... A teammate’s view reads the paths against their own clone. Sessions published before November 11, 2026 still hold the full paths they were captured with; publishing one again writes it the new way, though git history keeps the earlier copy (see Unpublish, and what it does not do). File contents the session changed are not copied when git already has them: the session keeps the git ids of each file’s before and after, and a teammate’s view reads them from their own clone of the repo. A session has a size cap of 2 MiB. Over it, the largest tool outputs are left out first (the view says where, and how large each was); your prompts and the agent’s replies are kept. In 30 days of real sessions measured for this, the middle session published about 270 KiB, and 344 of 350 needed nothing left out. A session so long that its conversation alone is over the cap (a few thousand turns) is not published, and orchestra session shared says so.

Publish, unpublish, and see what was shared

Every session you start is published when it ends, wherever the repo shares, including one you start from the terminal client. A session started private (press ctrl+p in the terminal client before you start it, or run orchestra start --private) is never published by the automatic path, and neither are its memories. The terminal says which it will be on the row that starts it, and a private session reads “private” in the list. If you make a session private after it was published, unpublish it too: making it private stops future publishing, it does not take back what was already pushed. Unpublishing a session works like unpublishing a memory: a new commit removes it, and teammates’ laptops drop their copy at their next refresh. It does not erase history, and your git host can still serve the old files to anyone who has their ids. The section below on unpublishing applies to sessions word for word.

See teammates’ sessions

Run orchestra with no command. On every plan, in a repo where sharing is on, its home lists the sessions teammates published, in History beside your own, newest first, each with whose it is. Your running sessions and teammates’ live ones stay at the top. Enter opens one read only. Home shows what this laptop last fetched, then refreshes from the repo’s git remote once each time you come back to it. It never waits for the remote: when the list may be behind, one line says so. With sharing off, that line says why instead. orchestra session teammates lists the same sessions, and the desktop app lists them in Sessions under Team, beside your own. The desktop app also lists there the sessions teammates are running now. Choosing one opens it in the app; Join in terminal in its menu opens it here, in the terminal client, to follow and steer it (orchestra tui <session id> does the same).

Commits name their session

orchestra enable installs a prepare-commit-msg git hook beside the post-commit one. A commit made inside a captured session gets a trailer:
Commits made in a worktree of the repository get it too. The second line appears once the session is published. The link lives in git itself, so it survives on any host, needs no app installed on the host, and reaches anyone who reads the commit. It is added once (an amend keeps it, never doubles it), never during a rebase, and never in an off-the-record session. A squash merge keeps it: GitHub’s default squash message lists each squashed commit’s message, trailers included.

Compared with Entire

Entire records agent sessions into git too, as checkpoints linked from commits by an Entire-Checkpoint trailer. The two fit together: If your team already runs Entire in a repo, Orchestra does not publish sessions there at all. It keeps Entire’s trailer, adds its own beside it, and when a memory cites a session, opening it reads Entire’s checkpoint instead. Nothing is stored twice.

Issues

On Orchestra Local, issues live on your laptop, and your team shares them through the repo’s git, the same way it shares memories and sessions. Nothing about an issue goes to Orchestra’s servers.
  • What travels. Each issue you or your agents create or change (its title, description, comments, status, assignee, priority, labels, project and parent) is recorded on your laptop as it happens. Your changes are published to your own ref, refs/orchestra/issues/<your id>, beside your memories and sessions and never in branch history. Every file there is encrypted with the team key, so the git host, a backup or anyone with read access who was never given the key sees only how many issues each person touched.
  • When. Your agents publish right after they write an issue, in the background, and so does a change you make in the desktop app. When that push brings something new, your laptop sends each teammate’s laptop that is online a short “fetch now” signal through Orchestra’s relay, and theirs fetches within seconds. The signal names the repo only by a scrambled id and carries nothing about the issue; the issues themselves still travel only through git. A laptop that was offline fetches as soon as it is back online, and again whenever an agent or the desktop app reads issues and the last fetch is more than 30 seconds old. To do both now, run orchestra issue sync in the repo.
  • Assigning. A teammate can be given an issue as soon as they are on the team, before they have shared anything, and an agent can be given one too. If their laptop is online, the assignee sees it on Home and in Issues within seconds; otherwise after their next fetch. A mention in a comment arrives the same way.
  • Two people editing at once. Every change is kept. When two people set the same field (both change the status, say) before seeing each other’s change, the later change wins, by when it was made, on every laptop. Both changes stay in the issue’s history, and comments are never lost: each one is added.
  • Issue keys. A new issue gets a short key, such as W-12: one past the highest number your laptop knows of, your teammates’ issues included. If two of you create an issue before your laptops have seen each other’s, both can get the same number. When the two meet, the one created first keeps the short key and the other gets a tag, such as W-4QXK-12, the same on every laptop. Keys made before this, which all carry a tag, still work.
  • Which repo. An issue goes to the repo its project is linked to. An issue that spans repos, or belongs to none, goes to the team repo when team_repo is set under [share]; without one, it goes to the one repo you share through, and if there are several, it stays on your laptop and orchestra issue sync says why. A teammate’s issue you change goes back to the repo it came from.
  • Before anything leaves your laptop, the same checks as memories run: redaction of secrets and personal details, the public repo refusal, and your yes at setup. An issue made visible to only some people is never published.
  • Needs the Team plan. A laptop on Free, or not signed in to a workspace on Team, publishes and fetches no issues, and orchestra issue sync says so in one sentence. Its own issues stay on it, usable as before.
  • Issues from Linear do not travel through git. Each person connects Linear on their own laptop (orchestra connect linear), and each laptop reads and writes Linear itself with that person’s own sign-in, kept in the laptop’s keychain. When one laptop changes a Linear issue, it tells teammates’ laptops to sync from Linear now, so they see it within seconds. See Linear on Orchestra Local.
  • Bringing issues from a hosted workspace. orchestra issue import, run in a shared repo, reads the issues of the hosted workspace that folder belongs to (or the one you name with --from) through your own sign-in and writes them to your laptop, with their comments, status, priority, labels, project, parent and links to the sessions that worked on them. They keep their refs, so W-297 still means the same issue. They are then shared with your team through git like any issue made here, so a teammate has them without importing. Nothing is written to the hosted workspace. Running it again adds nothing, and so does a teammate running it too. A comment someone else wrote keeps their name as its first line, and an assignee is kept when a person on your laptop has the same name. --dry-run says how many issues it would bring and writes nothing. Issues that belong to Linear are not imported: connect Linear on the laptop instead.
  • Stopping. orchestra issue leave --yes stops sharing every issue you published in the repo, and teammates’ laptops drop their copies at their next fetch. As with memories, history is kept and the host can still serve old files by id. Rotating the team key, or a laptop that does not hold it, works as for memories: copies it cannot read are dropped.

Teams with Local and hosted members

A team does not have to choose one. Someone on Orchestra Local and someone on Orchestra’s hosted workspace share through the same repo’s git, and each sees the other’s sessions and memories:
  • Local to hosted. When the repo is connected to your hosted workspace through the GitHub App, the workspace reads what Local teammates published and shows it in Sessions with a small “Shared through git” mark. Their memories reach your agent like anyone else’s. A laptop that is signed in tells the workspace right after it pushes, so this takes seconds. Otherwise the workspace looks every 30 minutes.
  • Hosted to Local. A team admin turns on sharing to git for the workspace’s hosted laptops in Settings, Integrations, under Sharing through git (or with orchestra session hosted-sharing on). From then on each person’s finished sessions share by default, unless they said no for the repo with orchestra session consent no. Their finished sessions and memories publish to the repo’s git when a session ends: from their laptop, with their own git credentials, through the same redaction and secret check as Local. Private sessions never are.
Who sees it in the hosted workspace follows the repo. Your laptop proves you can read the repo by sending one of its commits, which the workspace checks with GitHub. A member who has not proved it sees none of what came through git. On People, the workspace’s members are the team. Work from a Local laptop counts as its member’s once the workspace knows whose laptop it is: when that laptop pushes while signed in to the workspace, or when it belongs to a Local team on the same organization and its member has proved they can read the repo. Until then its publisher is listed apart, under Not in the team, and is never offered as an assignee.

Who can read it

Anyone who can read the repo can read its shared memory and sessions, and anyone who can read it and holds the team key can read its shared issues. Access follows the repo, exactly as the git host enforces it. There is no separate list. For memory that only some people should see, use a team memory repo with tighter access: set team_repo in .orchestra/config.toml and publish there with orchestra memory publish --team. Its readers are whoever the git host lets read that repo. A few things to know:
  • git clone --mirror, and any mirror or backup that fetches every ref, copies shared memory too. Treat mirrors with the same access as the repo.
  • Ordinary clones and fetches do not: shared memory, sessions and issues live beside the branches, under refs/orchestra/memory/, refs/orchestra/sessions/ and refs/orchestra/issues/, never in branch history, so they never show in git status, a pull request, or a normal clone.
  • Each person has one ref per repo. Its commits carry your git name and email, as your code commits already do.

Unpublish, and what it does not do

Unpublishing stops sharing from now on: it adds a commit that removes the memory, and teammates’ laptops drop their copy at their next index refresh, so their agents stop getting it. It does not erase:
  • History is kept. Every publish and unpublish is a new commit on top of the last one, so the commit that added the memory is still there.
  • Your git host can still serve the old file to anyone who has its id.
  • A teammate who already read it has read it.
That is why redaction and the secret check run before anything leaves your laptop: they are the protection, not unpublishing.

If a secret was published

  1. Rotate the secret first. Assume it is known.
  2. Run orchestra memory compact --yes. This is the one command that rewrites history: it replaces your shared memory history in that repo with a single commit holding only what you share now, and the new commit records what it replaced.
  3. Ask your git host to purge unreachable objects:
    • GitHub: contact GitHub Support and ask them to remove cached views and run garbage collection on the repository (see GitHub’s guide to removing sensitive data from a repository).
    • GitLab: run housekeeping with pruning on the project, or ask your administrator (GitLab’s guide to removing sensitive data covers it).
    • Bitbucket, Azure DevOps: contact the host’s support.
    • Self-hosted: run git gc --prune=now on the server’s copy.

When someone leaves

  • The team key changes on its own. When a person is removed from your Local team, the next publish in each of the team’s repositories makes a new key on that laptop and names it in git, on top of the old one. Laptops that stay on the team receive it from a teammate’s laptop as before; the person who left is never sent it, and their devices are named in git so no laptop ever hands it to them. If two laptops publish at that moment, they agree on one new key.
  • Old keys stay on each laptop. What was shared under the old key still opens for everyone who held it, and each person’s index moves to the new key at their next publish (or orchestra memory rekey).
  • A key you named in .orchestra/config.toml does not change on its own. orchestra doctor says when someone left after you got it. Make a new one (orchestra memory key new k2), hand it to everyone who stays, and change key in .orchestra/config.toml in a pull request.
  • They can stop sharing everything with orchestra memory leave --yes.
  • If they are gone, a teammate runs orchestra memory retire-person <id> --yes. It adds a commit, by the teammate, that unpublishes everything the person shared in that repo. Laptops drop the copies at their next refresh.
What someone who left can still read: what they already had. They keep the old key, so with read access to the repository they can still read what was shared under it before the key changed: issues sealed with it, and the index of every teammate who has not published since. They never get the new key, so issues shared afterward, and indexes rebuilt under the new key, are closed to them. What the key does and does not protect: it hides the words, file paths and names in the index, and the contents of shared issues, from anyone who does not hold it. It does not hide them from teammates, or from a former teammate who held the old key. Removing someone’s access to the repo is what stops them reading shared memory.

Git host support

Shared memory needs the git host to accept refs outside branches and tags, and works best when the host supports partial clone (fetching file listings without file contents) and fetching one object by id. Run the check yourself against any remote:
What happens when a check fails:
  • No custom refs: shared memory cannot live in that host. Put a team memory repo on a host that supports them.
  • No partial clone: everything still works, but every laptop receives every shared memory along with the index. orchestra memory shared says so.
  • No single object by id: a fetch brings that person’s whole set of shared memories into a temporary folder, keeps the one asked for, and deletes the rest.
Branch protection and rulesets: on GitHub, branch and tag rulesets apply to branches and tags only, so they do not block shared memory. Push rulesets (blocking file paths, sizes or extensions) apply to every push, including shared memory. Shared memory files are small Markdown files under mem/ plus one index.seg file. If your host or a server-side hook restricts which refs can be pushed, allow refs/orchestra/memory/*, refs/orchestra/sessions/* and refs/orchestra/issues/*.

Commands