Trackers and Team Knowledge
New. Linear and Jira sync is behind the trackers feature flag; Notion knowledge is behind knowledge. Both are on by default. Turn one off in Settings → Feature flags or with shep settings flags disable trackers / shep settings flags disable knowledge.
A connection is an account Shep reads from: Linear or Jira for issues, Notion for documents. Each connection belongs to a space, so a work Jira and a personal Linear stay apart.
- Trackers keep Linear or Jira issues in a Shep project as work items, and can write changes back.
- Knowledge sources keep Notion pages or databases as team knowledge that agents in the space read when it fits their task.
Connect an account
| Tool | What you need |
|---|---|
| Linear | A personal API key (Linear settings → Security & access) |
| Jira | Your site URL (https://acme.atlassian.net), your account email and an API token from https://id.atlassian.com/manage-profile/security/api-tokens |
| Notion | An internal integration token (Notion → Settings → Connections → Develop or manage integrations). Then share each page or database you want Shep to read with that integration (••• → Connections → Add connection) |
From the terminal:
shep connection add linear --name "Acme Linear" --space acme # prompts for the key
shep connection add jira --name "Acme Jira" --space acme \
--site https://acme.atlassian.net --email me@acme.com # prompts for the token
shep connection add notion --name "Acme Notion" --space acme # prompts for the tokenThe key is prompted for with hidden input, never passed as an argument. In scripts, put it in an environment variable and name the variable:
LINEAR_KEY=lin_api_… shep connection add linear --name CI --secret-env LINEAR_KEYShep checks the key against the service before saving it, stores it encrypted in its local database, and does not show it again. Without --space the connection belongs to the default space.
In the browser, open Connections in the sidebar (/connections), choose the tool, name the connection, pick the space, paste the key and press Connect.
| Command | Does |
|---|---|
shep connection add <linear|jira|notion> -n <name> [-s <space>] [--site <url>] [--email <email>] [--secret-env <VAR>] | Connect an account |
shep connection ls | List connections |
shep connection test <connection> | Check the credentials again |
shep connection rm <connection> | Remove a connection with its sync rules and knowledge sources. Work items it already synced stay |
If a key stops working (revoked, expired), the connection shows Error with the service’s message and its rules or sources fail until it works again. Test / shep connection test re-checks it; the next clean run clears the error.
Tracker sync (Linear, Jira)
Add a sync rule
A rule says what to read and which Shep project it lands in:
- Linear: a team key, such as
ENG. - Jira: any JQL query, such as
project = PAY AND type = Bug.
shep sync rule add acme-linear --project payments --scope ENG
shep sync rule add acme-jira --project payments --scope "project = PAY AND type = Bug" --two-way --every 30You need a project first (shep project new, see Projects). On the Connections page the same form sits under each connection.
| Option | Meaning |
|---|---|
-p, --project <project> | Shep project slug or id (required) |
-s, --scope <scope> | Linear team key or Jira JQL query (required) |
--two-way | Also push Shep changes back to the tracker. Without it the rule only imports |
--every <minutes> | Minutes between automatic runs: 5 to 1440, default 15 |
Let it run
The Shep daemon runs every enabled rule on its interval. Each run asks the tracker only for issues changed since the last run. To run now: Sync now on the Connections page, or:
shep sync run # every enabled rule
shep sync run <rule> # one ruleEach rule shows what its last run did: created, updated, pushed, conflicts and failed. A synced work item shows its issue key (for example ENG-42) next to its title, linking to the tracker.
| Command | Does |
|---|---|
shep sync rule ls [connection] | List rules with their last run |
shep sync rule disable <rule> | Stop the daemon running a rule (Pause in the browser) |
shep sync rule enable <rule> | Let the daemon run it again (Resume) |
shep sync rule rm <rule> | Remove a rule; synced work items stay |
What is synced
| Field | Into Shep | Back to the tracker (two-way) |
|---|---|---|
| Title | ✓ | ✓ |
| Description | ✓ (Jira rich text becomes Markdown) | ✓ |
| Status | ✓ (mapped to the project’s Backlog, Unstarted, Started, Completed or Cancelled state) | ✓ |
| Priority | ✓ | ✓ |
Comments, labels, assignees and attachments are not synced.
When a work item moves to a completed state in Shep, a two-way rule moves the Linear issue to the team’s first “completed” state, or takes the Jira transition into a done status.
When both sides changed. Shep remembers each field’s value at the last sync. If only the tracker changed a field, Shep takes it; if only Shep changed it, a two-way rule pushes it. If both changed the same field to different values, the tracker wins and the run counts a conflict.
Good to know:
- Removing a rule or connection keeps the work items it synced.
- A work item you delete in Shep is not imported again.
- If the tracker rate-limits Shep, the run stops and says so; the next run picks up where it left off.
Team knowledge (Notion)
Add a source
A knowledge source is one Notion page with the pages under it (up to five levels deep), or one database (every row). Pass its link:
shep knowledge source add acme-notion \
--scope https://www.notion.so/acme/Engineering-handbook-0123456789abcdef0123456789abcdef
shep knowledge source add acme-notion --scope <payments PRD database link> \
--product-line payments --every 240| Option | Meaning |
|---|---|
--scope <link> | Link or id of a Notion page or database shared with the integration (required) |
-l, --product-line <line> | Only repositories of this product line read it. Without it, the whole space does |
--every <minutes> | Minutes between automatic syncs: 15 to 1440, default 60 |
On the Connections page the same form sits under the Notion connection.
Sync
The daemon syncs each enabled source on its interval. A sync reads only the pages edited since the last one and drops pages that were deleted or unshared. To sync now: Sync now on the Connections page, or:
shep knowledge sync # every enabled source
shep knowledge sync <source> # one source| Command | Does |
|---|---|
shep knowledge source ls | List sources with their last sync (added, updated, removed, failed) |
shep knowledge source disable <source> / enable <source> | Stop or resume scheduled syncing |
shep knowledge source rm <source> | Remove a source and the documents it synced |
shep knowledge ls [-s <space>] | List a space’s knowledge documents |
shep knowledge search "<task>" [-r <repo>] | Show the passages an agent working in that repository would get for that task |
The Project Memory page also lists each space’s documents, with links back to Notion.
What agents see
When an agent starts work in a repository, Shep splits the space’s documents into sections by heading, ranks the sections against the task by shared words, and adds the best ones — about 1,000 tokens — to the agent’s prompt under Team knowledge, each naming its page and section. Check what a task would pull in:
shep knowledge search "refund guest orders" --repo ~/src/payLimits and behaviour:
- Shep only reads Notion; it never edits it.
- Up to 500 pages per source and 100,000 characters per page are kept.
- Images, files and embeds become placeholders; tables, lists, code and callouts keep their shape.
- Ranking is by words, not meaning. A task phrased very differently from the page may not match it.
See also
- Spaces
- Projects and the bug loop — investigate synced bugs
- Opportunities — discovery also reads document titles