Skip to Content

Spaces and Product Lines

New. Behind the spaces feature flag (on by default). Turn it off in Settings → Feature flags or with shep settings flags disable spaces. Settings you already saved on a space keep applying to runs while the flag is off.

A space keeps one body of work apart from another: a client, your employer, your side projects. A product line is a group of repositories inside a space, such as Acme’s payments services.

Spaces decide two things:

  1. How far knowledge travels. Project memory, Notion knowledge, signals, opportunities and incidents belong to a space. Nothing written in one space is read by agents in another.
  2. Who the agents are. A space can give its feature runs their own Claude login, GitHub account, git author, AWS profile and list of allowed agents.

A fresh install has one space, Default. Until you add another, everything lands there and nothing changes.

Where a repository lands

Every repository belongs to exactly one space. Shep decides which, in this order:

  1. A pin. You assigned this repository to a space with shep space assign or Pin to space… on the Spaces page.
  2. A rule. The most specific matching rule wins. A rule is a folder prefix (~/work/acme) or a git remote pattern (github.com/acme/*). In remote patterns * matches within one segment and ** spans segments. Equally specific rules are ordered by priority (lower wins, default 100).
  3. The default space. Everything else.

A rule can also name a product line that matching repositories join.

Set it up from the terminal

shep space new Acme -d "Client work for Acme" -c "#3456c4" shep space line new acme Payments shep space rule add acme "github.com/acme/*" shep space rule add acme "github.com/acme/pay-*" -l payments shep space show ~/work/acme/pay-api

shep space show prints the space, the product line and why:

Space Acme Product line Payments Because matched Remote rule github.com/acme/pay-*

Spaces, lines and rules are addressed by name, slug or id. The slug is printed when you create one (Acme → acme).

CommandDoes
shep space lsEvery space with its product lines, repository count and memory count
shep space show [path]Which space and product line a repository is in, and why (current directory if omitted)
shep space new <name> [-d <text>] [-c <#hex>] [--default]Create a space; --default makes it the default
shep space edit <space> [-n <name>] [-d <text>] [-c <#hex>]Rename it or change its description or colour
shep space default <space>Make it the space unmatched repositories land in
shep space rm <space>Delete it with its rules, pins and product lines
shep space line new <space> <name> [-d <text>]Add a product line
shep space line rm <space> <line>Remove a product line; its repositories stay in the space
shep space rule add <space> <pattern> [--remote] [-l <line>] [-p <n>]Add a rule. Shep tells a path from a remote pattern by its shape; --remote forces remote
shep space rule ls [space]List rules
shep space rule rm <id>Remove a rule
shep space assign <space> [path] [-l <line>]Pin a repository, overriding every rule
shep space unassign [path]Remove the pin so the rules apply again
shep space config <space> [options]Show or change how agents run in the space (below)

Set it up in the browser

Open Spaces in the sidebar (/spaces).

  1. Create a space with a name and, optionally, a description and colour.
  2. Add product lines to it.
  3. Add rules: type a folder or a remote pattern and optionally pick the product line.
  4. Check the Repositories table. It shows each repository’s space, product line and the reason (Pinned, Rule or Default space). Use Pin to space… to override the rules for one repository.

The Spaces page: a form to create a space, and three space cards. Default has no product lines or rules; Acme Store has the product lines Payments and Storefront, a path rule for /home/demo/code/acme-store mapped to Storefront and a remote rule for github.com/acme/*; Internal tools has an Ops dashboards product line and a path rule. Each card has Agent settings marked "Inherits the host"

Memory reach

Shep’s agents write lessons into project memory after merged features. Each entry has a reach, which you change on the Project Memory page with Change who sees this:

ReachWho reads it
This repository onlyAgents working in the repository that learned it (the default)
Its product lineEvery repository in the same product line
Its whole spaceEvery repository in the same space

No reach crosses a space. Moving a repository to another space takes its repository-only entries with it; entries it shared stay where they were written.

Per-space logins, identity and agents

Anything you leave empty inherits your machine’s setup. Shep never stores a password or token for this: you give each tool its own config directory and log in there once.

# A separate Claude login for Acme work CLAUDE_CONFIG_DIR=~/.claude-acme claude # log in, then exit # A separate GitHub account for Acme work GH_CONFIG_DIR=~/.config/gh-acme gh auth login shep space config acme \ --claude-config-dir ~/.claude-acme \ --gh-config-dir ~/.config/gh-acme \ --git-name "Ada Lovelace" --git-email ada@acme.com \ --agents claude-code,codex-cli

From then on every feature run in an Acme repository — its agent and every git and gh command it runs, including the pull request it opens — uses those logins and that identity. Chat sessions about a feature, bug investigations, discovery and incident triage in the space use them too.

OptionSets for agent processes
--claude-config-dir <dir>CLAUDE_CONFIG_DIR, and removes ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN so they don’t override it
--gh-config-dir <dir>GH_CONFIG_DIR, and removes GH_TOKEN, GITHUB_TOKEN, GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN
--git-name <name>GIT_AUTHOR_NAME and GIT_COMMITTER_NAME
--git-email <email>GIT_AUTHOR_EMAIL and GIT_COMMITTER_EMAIL
--aws-profile <name>AWS_PROFILE
--bedrock / --no-bedrockSets CLAUDE_CODE_USE_BEDROCK=1 / removes it, whatever the host sets
--agents <list>Comma-separated agent types the space allows (claude-code, codex-cli, cursor, gemini-cli, …). Empty allows every agent
--pr-comments off|mention|allWhich review comments on Shep’s pull requests are answered without asking (default mention, i.e. comments containing #shep). See PR comments
--resolve-threads / --no-resolve-threadsResolve a review thread after changing code for it
--auto-actions <list>Runtime actions run on incidents without approval: restart, rollback, scale. See Incidents
--docs-first / --no-docs-firstDocs-first mode. See Docs first
--docs-paths <list>Documentation paths for docs first (default docs/,README.md)
--clear <fields...>Return fields to “inherit”: claude-config-dir, gh-config-dir, git-name, git-email, aws-profile, bedrock, agents, pr-comments, resolve-threads, auto-actions, docs-first, docs-paths

shep space config acme with no options shows the settings and exactly which variables a run gets (Sets / Removes).

If a space allows only some agents, a run with another agent stops before it starts and says why. Change the run’s agent or the space’s allowed agents.

In the browser, expand Agent settings on the space’s card on the Spaces page. The card shows Customised or Inherits the host.

Agent settings form on a space card: Claude and gh config directories, git author name and email, AWS profile, Amazon Bedrock choice, allowed agents checkboxes, pull request comment trigger, runtime actions allowed on incidents, and Require docs first with documentation paths

Things to know

  • Deleting is guarded. Shep refuses to delete a space that still holds memory, or a product line that memory is shared with, and says how many entries are in the way. The default space can’t be deleted; make another space the default first.
  • Not everything uses the space login. The Shep web server’s own GitHub calls, such as listing repositories to import, use your machine’s login. Claude transcripts for a space with its own Claude config directory live in that directory, so the web UI’s session list shows only the default login’s transcripts.
  • Entries from before spaces. Memory entries that were “organization-wide” now read as space-wide inside the space they were written in, which on an upgraded install is the default space.

See also