agentgraph-connector-twg

An AgentGraph connector for the Atlassian Teamwork Graph, built on the twg CLI.

People become Person entities from reporters, assignees, commenters, authors, editors, video owners, Atlas owners and update authors, and @ mentions. Relationships from twg context jira workitem, Jira issue links, and Atlas goal/project links become references edges, with stub entities for linked resources that have not been fetched yet.

This package is kept outside the AgentGraph repository because twg is internal Atlassian tooling.

Requirements

• AgentGraph 0.7.0 through 0.7.x (it provides the Task and Video entity types this connector emits).
• The twg CLI, authenticated. The connector never authenticates on your behalf. It reads through twg jira, twg confluence, twg loom, twg context, and — for Atlas — twg goals get and twg projects get.

Install

uv pip install agentgraph-connector-twg

Releases through 0.2.0 were published privately as atlassian-agentgraph-connector-twg; the Python import package is unchanged.

Confirm registration and configure your site:

agentgraph list-connectors

agentgraph connector twg add-site <site>

agentgraph connector twg status

Authentication

twg owns the Atlassian OAuth session. When it expires, the connector reports it and every fetch returns the same remediation:

twg auth refresh

Run that in a real terminal. twg needs write access to ~/.config/twg, which a sandboxed agent cannot grant. Under the com.agentgraph.server LaunchAgent the server can refresh the session itself.

If twg is not on PATH — likely under launchd — the connector probes ~/.local/bin/twg, /opt/homebrew/bin/twg and /usr/local/bin/twg. Set AGENTGRAPH_TWG_BIN to override.

Configuration

Settings live in <agentgraph-config-dir>/twg.json (usually ~/.agentgraph/twg.json) and are managed through the CLI:

<site> is the tenant name, and a site URL is accepted in its place. Both host spellings are understood, so hello, hello.atlassian.net and the per-product domain a migrated tenant is served from (hello.jira.atlassian.cloud, hello.confluence.atlassian.cloud) all configure the site hello, and browsing either host is observed. Anything else is rejected rather than stored.

Refresh behaviour

• Observe / fetch: browsing or fetching a supported URL fetches that resource. Confluence short links (/wiki/x/<tiny>) are resolved through twg resolve.
• Poll (every 30 minutes): twg work query --scope me covers your own recently touched work items, pages, and videos, hydrating at most poll_item_limit (default 50) resources per run and skipping anything fetched within the last 15 minutes.
• Ingest: the same sweep over ingest_since (default 90 days), plus every configured JQL query and Confluence space.
• Atlas goals and projects are indexed on observation or an explicit agentgraph fetch only. They are not part of the poll or the ingest sweep, and there is nothing to configure for them: home.atlassian.com/o/<orgId>/s/<cloudId>/(goal|project)/<KEY> carries everything a fetch needs. Because that host is not site-scoped, Atlas observation is not narrowed to the configured sites.
• JPD ideas are Jira work items, so they ride the Jira paths above with no extra configuration.

Only your own activity and explicitly configured scopes are indexed.

Data locality

Indexed Jira, Confluence, and Loom content — including transcripts — is stored in the local AgentGraph SQLite database and becomes readable by any MCP client you connect. This is internal work data; choose your polled scopes deliberately.

Development

uv sync

That installs the dev dependency group and resolves AgentGraph from PyPI per uv.lock. Run the same gates CI does (.github/workflows/ci.yml):

.venv/bin/python -m pytest -q
.venv/bin/python -m ruff check .
.venv/bin/python -m pyright

Tests never invoke the real twg: the subprocess layer is patched and payload fixtures live in tests/conftest.py. Those fixtures follow the field paths reported by twg help describe "<command>". Re-record them from live output when a twg upgrade changes a payload, and keep parsing tolerant — payloads.py reads the documented field first and falls back to known aliases.

Against a local AgentGraph checkout

To develop this connector against an unreleased AgentGraph — a new entity type or a change to BaseConnector — install that checkout editable over the resolved one:

uv pip install -e ../agentgraph --config-setting editable_mode=compat

editable_mode=compat is what keeps pyright working. A default editable install writes a runtime import hook that pyright cannot follow statically, so every agentgraph import resolves to nothing and cascades into roughly a thousand unknown-type errors. compat writes a plain path entry instead, and the committed [tool.pyright] config then resolves the checkout unchanged.

uv.lock still pins agentgraph-server to a published release, and uv run/uv sync sync exactly against it — either will silently revert this install. Run the gates through .venv/bin/python as above, not uv run. If ModuleNotFoundError: No module named 'agentgraph' appears, or pyright suddenly reports hundreds of unknown types, the install was reverted: run the command again. To go back to the released AgentGraph deliberately, uv sync.