Metadata-Version: 2.4
Name: teamctx
Version: 0.1.0
Summary: Deterministic ambient context for software teams
Project-URL: Homepage, https://teamctx.dev
Project-URL: Repository, https://github.com/teamctx/teamctx
Project-URL: Issues, https://github.com/teamctx/teamctx/issues
Author: teamctx contributors
License: Apache-2.0
License-File: LICENSE
Keywords: confluence,context,developer-tools,github,gitlab,jira
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: click<9.0,>=8.1
Requires-Dist: pydantic<3.0,>=2.7
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mcp>=1.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# teamctx

Before you or your coding agent touch files, teamctx tells you what changed, what conflicts, what
failed, and what it could not verify, as source-backed evidence you can judge.

## Why

When you work through a coding agent, the expensive failures are not slow context gathering. They
are confident wrong context: the agent edits a file an open pull request is already changing, builds
on an acceptance criterion that moved, or proceeds on a "green" CI that is actually red. A wrong
answer delivered through a terminal you trust is worse than no answer.

teamctx keeps you and your agent pinned to the current, source-backed state of the systems your team
already uses. Its defining property is that there is no LLM in the content path. It normalizes,
routes, selects, and renders the record, and it never reinterprets what the record means. So facts
arrive faithful to the record, source-backed, and the same way every time. A green means checked, not guessed, and
where teamctx could not look, it says so plainly instead of implying all is well.

## What it checks

Run it before you start editing. From the systems of record your team already uses, teamctx surfaces:

- Open pull requests or merge requests that touch the files you are about to change. Your own
  same-repo PR or MR for the branch you are standing on is set aside with an FYI, never flagged
  against you (a fork PR still surfaces, on purpose).
- Checks and pipelines that are failing on your branch, along with ones that are still running,
  skipped, or canceled, each surfaced honestly as not yet confirmed green.
- Acceptance criteria that changed since you started, on a linked GitHub issue or a Jira issue.
  The issue and the start time are derived from your branch name (a Jira key like PROJ-123, or a
  GitHub issue number), commit trailers, and merge point when you don't name them, and the
  derivation is named in the output so you can judge it.
- Design docs you rely on that have been superseded: a doc under your declared docs folder that
  names a newer replacement, or a Confluence page marked with the teamctx.superseded_by property,
  whether or not you are editing it.

Live today, across four sources: GitHub and GitLab forges (open pull requests and merge requests,
plus check runs and pipelines), GitHub issues and Jira for acceptance criteria, and local docs
folders and Confluence spaces for superseded docs. This four-source behavior was exercised by a
live multi-actor emulation: one operator driving several actor roles, human-style and agent-style,
through real GitHub, GitLab, Jira, and Confluence, with the run and its evidence committed at
`docs/validation/team-emulation-2026-07-04/SUMMARY.md` (in the repository).
teamctx reads metadata only (it does not read pull request bodies, comments, or patches), speaks
only to the structured slice it can actually verify, and does no broad search or summaries. A source
becomes supported only after it proves the same honest-coverage behavior.

## Install

teamctx is pre-release. Install from source:

```bash
git clone https://github.com/teamctx/teamctx
cd teamctx
pip install -e .
```

It needs read access to GitHub. If you use the GitHub CLI and are logged in (`gh auth login`),
teamctx picks that up automatically. Otherwise set a token in the environment (teamctx never stores
the value):

```bash
export GITHUB_TOKEN=ghp_...
# or point at a file instead:
export GITHUB_TOKEN_FILE=~/.config/teamctx/token
```

For a GitLab project, set a GitLab token the same way:

```bash
export GITLAB_TOKEN=glpat-...
# or point at a file instead:
export GITLAB_TOKEN_FILE=~/.config/teamctx/gitlab-token
```

For Jira and Confluence, teamctx uses Atlassian Cloud basic auth: your account email and an API
token. Both halves must be present, or the source reports itself unavailable and names the missing
half.

```bash
export ATLASSIAN_EMAIL=you@example.com
export ATLASSIAN_API_TOKEN=...
# or point the token at a file instead:
export ATLASSIAN_API_TOKEN_FILE=~/.config/teamctx/atlassian-token
```

Which sources teamctx checks lives in the committed `.teamctx/config.json`. `teamctx onboard`
writes the forge and docs folder for you; add the `jira` and `confluence` blocks to turn those
sources on:

```json
{
  "schema_version": "teamctx.project_config.v0",
  "work_start": {
    "repo": "acme/widgets",
    "forge": "github",
    "docs_root": "docs",
    "jira": { "base_url": "https://your-site.atlassian.net" },
    "confluence": { "base_url": "https://your-site.atlassian.net", "space_key": "ENG" }
  }
}
```

## Quickstart

```bash
# 1. One command sets it all up: detects the repo, writes a shareable .teamctx/config.json,
#    installs the Claude Code reflex hook, adds the CLAUDE.md snippet, and reports your
#    credential and a live reachability check. Idempotent; re-run any time. --dry-run previews.
teamctx onboard

# 2. That's it. From now on, team context appears by itself: before the first edit of each
#    Claude Code session and again whenever something changes while you work; agents get the
#    same answer over MCP. What appears at the start looks like
#    the samples below (from a branch named 42-fix-auth in a repo with a docs/ folder, so
#    all four checks fire). To reproduce them by hand:
teamctx work-start --path src/auth/token.py
```

A clean start reads:

```
Looks clear to start.
  Checked: no other open PRs touch your files; the linked issue's criteria are unchanged (issue #42 from your branch name); the docs you rely on are current; no failing checks found.
```

When something is in the way:

```
Before you start, here is what to handle first:
  • Open PR #7 changed src/auth/token.py: look at it before you edit so you don't undo each other's work (gh pr view 7 --repo acme/widgets)
  Also checked: the linked issue's criteria are unchanged (issue #42 from your branch name); the docs you rely on are current; no failing checks found.
```

When the only overlapping PR is your own branch's PR, that is not a collision, and teamctx says so
instead of crying wolf:

```
Looks clear to start.
  Checked: no other open PRs touch your files; the linked issue's criteria are unchanged (issue #42 from your branch name); the docs you rely on are current; no failing checks found.
  FYI: Your own open PR #12 for this branch touches these files; not flagged as a collision.
```

And when it could not verify something that matters, it says so rather than guessing. This
last sample is a different situation: a branch with no derivable issue, no docs folder
configured, and GitHub unreachable:

```
Heads up: I can't confirm the important things yet:
  • Open PRs and failing checks: teamctx couldn't reach GitHub. Either it has no access yet (set GITHUB_TOKEN, or GITHUB_TOKEN_FILE with a path to a token file) or it's a temporary connection issue. Until it's back you won't see colliding PRs or red CI on your files.
  Not checked: spec changes (no issue could be derived from your branch or commits; name one with --issue); docs (no docs root is configured; set work_start.docs_root to enable).
```

## Drill into a finding

To audit one finding (its full evidence, or how to open the source):

```bash
teamctx why pr:7 --path src/auth/token.py
teamctx open-source pr:7 --path src/auth/token.py
```

Selectors are the handles you see in the output: `pr:N`, `issue:#N`, `path:X`, `doc:PATH`, `gate:NAME`.

## It appears on its own

Team context is ambient by design: after onboard, nobody runs a command in daily use. The opt-in
Claude Code hook that onboard installs grounds the session before its first edit and then keeps
watch: it quietly re-checks at an interval and speaks again when something actually changed
("since you started: GitHub PR #7 appeared, touching src/auth/token.py"); a standing gap it
cannot verify is re-stated every so often rather than forgotten. Silence means checked and
unchanged within the interval. The CLAUDE.md instruction onboard writes tells any
agent how to receive and use what appears (with a fallback for environments that do not run
hooks). If you only want the hook without the rest of onboard:

```bash
teamctx install-hook
```

The hook never blocks an edit. It just surfaces what is happening around the file you are about to
touch.

## The promise, stated honestly

- A green means checked, not guessed. teamctx never folds a coverage gap into a clear.
- Where it could not look (no access, a source down, or more results than it could enumerate), it
  returns Unknown, never a false all-clear.
- There is no LLM in the content path. teamctx is the reference for what is currently true in the
  record. It is not the judge of what the right call is (that is your job), and it does not claim to
  make the record itself correct (it delivers the record faithfully).

## How the claims are proven

Two layers back the behavior above. An offline emulation harness (`emulation/`) drives the real
CLI, hook, and MCP tool through a sixteen-row scenario matrix against bundled mock GitHub, GitLab,
Jira, and Confluence servers; anyone can run it with `python emulation/runner.py --offline --all`,
and each expected block quotes the real renderer. On top of that, a live multi-actor run against
real GitHub, GitLab, Jira, and Confluence is committed as evidence at
`docs/validation/team-emulation-2026-07-04/SUMMARY.md` (in the repository),
including the two residuals it left open.

## What it is not

teamctx is deliberately bounded:

- No LLM and no agent runtime. It informs; it does not act or decide.
- No broad enterprise search, summaries, or fuzzy question answering.
- No productivity analytics and no presence tracking. It reads work artifacts and does not score or
  summarize people.
- It does not read private messages, pull request bodies, or patches, and it does not write to your
  source systems.

## How it works

Each connector reads approved metadata from a source and emits a typed, source-backed contract. A
deterministic core composes them, derives the findings, and returns one verdict per check with an
honest account of what it could and could not cover. The CLI output, the MCP tool result, and the
hook signal all derive from one broker answer and one shared classification; the hook says less on
purpose, but nothing it says can disagree with the full report. Replay the same inputs and you get
the same verdict every time.

Positioning and design: `docs/product/vision/reality-grounding-strategy-2026-06.md` (in the repository).
