Connectors extend hashd with external integrations (Figma, GitHub, Bitbucket, Jira). They're auto-discovered at startup through the hashd.connectors entry point group. Core never references a specific connector.
See Building Connectors for the developer guide.
Every connector declares its capabilities via module-level attributes in __init__.py. All are optional.
# packages/hashd-connector-my/src/hashd_connector_my/__init__.py
CONNECTOR_NAME = "my_connector" # unique, used as @ namespace
CONFIG_SECTION = "my_config" # config.yaml section
CLI_COMMANDS = {
"mycommand": (register_fn, dispatch_fn), # register returns parser, dispatch takes (args, ops_dir, project_config)
}
DOCTOR_CHECKS = [check_fn] # (project_dir) -> list[DiagnosticResult]
IS_CONFIGURED = is_configured_fn # (project_dir) -> bool
ARTIFACT_RESOLVER = resolver_fn # (project_dir, refs: list[str], fetch: bool) -> dict[str, ResolvedArtifact]
CACHE_DIR_NAME = "my_connector" # .cache/<this>/
TOOLS = [ # list of ToolSpec
ToolSpec(name="my_browse", description="...",
parameters={"query": "..."}, handler=fn),
]
AUTOCOMPLETE = autocomplete_fn # (project_dir, partial) -> list[(value, description)]
EVENT_HANDLER = handler_factory # (project_dir) -> object with handle(event) -> None
EVENT_TYPES = ("workstream_ready_to_merge",) # the connector event types it takes
CONFIG_FIELDS = ( # project settings `hashd connector <name>` shows and writes
ConfigField(key="url", label="Site URL", type="string", sensitive=False, required=True, destination=True,
description="Your site's address."),
)
DISPLAY_NAME = "My Connector" # shown instead of the name
ICON_LIGHT = "icon-light.svg" # SVG files in this package: for light and dark backgrounds
ICON_DARK = "icon-dark.svg"
ABOUT = "ABOUT.md" # markdown file in this package: the About page
LOGIN_METHODS = ( # how a person signs in to the destination
LoginMethod(label="API token", description="...", help_url="https://...",
fields=(CredentialField(key="api_token", label="API token", secret=True),)),
)
ACCOUNT_DESTINATION = site_of # (typed text) -> the destination an account is stored fordiscover_connectors() finds connectors from one source:
- Entry points: pip-installed packages declaring the
hashd.connectorsgroup
Import errors are logged and skipped. Namespace collisions (two connectors with the same CONNECTOR_NAME) are fatal -- hashd refuses to proceed.
Shipped connectors are registered in pyproject.toml:
[project.entry-points."hashd.connectors"]
github = "hashd_connector_github"
figma = "hashd_connector_figma"
jira = "hashd_connector_jira"Web Settings → Connectors lists every installed connector from
GET /connectors/overview, with its declared name, icons, About and the
server's one-word state. Each connector's page edits its declared settings
(PUT /connectors/config), stores your own account from its LOGIN_METHODS
for the destination the server resolved (PUT /connectors/accounts), shows
what it does, and runs its checks as you (GET /connectors/check). Nothing in
the Web module names a connector.
Under Advanced on that page, and in the TUI Project Configuration, one
explicit setting key can be written under the connector's CONFIG_SECTION
for keys it does not declare. They do not load or prefill stored values. Save
writes a project override; an explicitly confirmed empty save writes a blank;
Reset removes only the named override. YAML configuration and connector
environment-variable credentials remain supported.
Connector CONFIG_SECTION declarations also enable config set/get/reset for
free-form dotted settings at system and project scope. For example,
hashd project config set jira.url https://company.atlassian.net writes a project
override. This declares a namespace, not field names or types: a typo such as
jira.ur is accepted, and the connector's loader/doctor owns field validation.
Existing credential support is unchanged, including Jira YAML values and
environment overrides; Figma stores its token environment-variable name.
The existing project config batch API deep-merges partial connector objects, so changing Figma's profile retains its file ID and other settings. Dotted-key reads and resets use the same declarations. Schema-based completion/diff/reset-all do not enumerate free-form connector leaves; address a known leaf or section explicitly. Host discovery failures are reported instead of claiming a key is unknown. Ordinary schema settings do not require a connector-host lookup.
A connector declares the project settings that say where it points in
CONFIG_FIELDS. The declaration is the allowlist: these commands show and write
only declared fields, never another key in the section, and a field states
sensitive=False explicitly -- a secret cannot be declared, because credentials
are personal accounts, never project settings. Each field is typed (string,
or enum with its choices). required means no operation works without it;
a field only some operations need lists them in needed_for (references --
resolving @connector:ref; picker -- searching or browsing for one; notes,
events, checks), so an optional mode stays configurable and each operation
says why it is unavailable: a ClickUp task or Azure work item referenced by id
resolves without the List or project the picker needs. destination marks the field personal
accounts are stored for. A string field may carry a pattern the whole value
must match. Python (re.fullmatch) and Go (anchored) both apply it, so keep
it to anchored ASCII literals and character classes such as ^[0-9]+$, and add
it to tests/fixtures/connectors/pattern_samples.json, which holds both sides
to the same answers. Values are read as the connectors' loaders read them:
trimmed, a blank one is absent, and a present null is invalid. A present
value that fails its pattern, its choices or its type is reported invalid,
never shown, and never replaced by an inherited one, and it blocks every
operation, since the loaders validate the whole section first; an absent
optional one blocks only what needs it. The host and the server both refuse a declaration that
breaks these rules. Nested settings (lifecycle, events, notes) are not
declared and stay on hashd project config set.
configure --set KEY=VALUE --unset KEY(PUT /connectors/config) validates the whole request against the declaration, then writes it in one rewrite of the project'sconfig.yamlunder the project lock.--unsetremoves this project's value; a value inherited from system configuration still applies. With no flags it lists the settings.status(GET /connectors/status) reads only local facts: the declarations (asked with no project directory, so no connector code runs against the project), the configuration files, and whether you have a personal credential for the destination. It reports the destination, your personal authentication, and per operation whether its settings are set and you have a credential -- not a remote health claim.check(GET /connectors/check) checks the settings, then runs the connector's ownDOCTOR_CHECKSwith your personal credential. It never uses project, environment or host credentials, in solo or team mode: without a personal credential the authenticated check is refused, and a connector with no personal accounts gets none. The credential is bound to its destination: the request names the destination it was chosen for, and the connector host refuses before any check runs unless the connector, loading its configuration there (environment overrides included), still points there: itsACCOUNT_DESTINATIONof itsREMOTE_SCOPEis the account's destination (for GitHub, the issues repository's host). The doctor checks reached here only read; GitHub's reads the credential and the repository on the repository's own host (gh api --hostname), nevergh auth status, which tests every account on every host.
| Connector | Personal credential | Destination |
|---|---|---|
| GitHub issues | your account for the issues repository's host (hashd connector login github): an Issues token, or your forge login if you choose it; never the code repository's remote |
github.repo |
| Jira | your account (hashd connector login jira) |
jira.url |
| Azure Boards | your account (hashd connector login azure) |
azure.organization_url |
| ClickUp | your account (hashd connector login clickup) |
clickup.workspace_id |
| Confluence | your account (hashd connector login confluence): Atlassian email and API token; it declares no checks |
confluence.url |
| Figma | your account (hashd connector login figma): a personal access token |
none: every Figma account is for figma.com |
Note the order: hashd connector status jira lists your Jira accounts;
hashd connector jira status reports the project's Jira connector.
A connector that serves one place declares no destination field: its
ACCOUNT_DESTINATION names that place from no text, so hashd connector login figma needs no --destination.
Team-mode reads. In team mode the connectors above with a personal
credential (GitHub issues, Jira, Azure Boards, ClickUp, Confluence, Figma) are read the same way
a check is: with your credential for the project's destination, pinned to
it, and never with the project's config.yaml credentials, the server's
environment or its gh login. This covers reference search
(GET /connectors/search), preview, the story-source availability a picker and
an import read (GET /connectors/capabilities), and the connector checks in
hashd doctor. Without a usable credential of your own the read is refused and
says how to connect one (hashd connector login ...); nobody else's account
is used instead. Under
your credential, the credential fields in config.yaml are not read at all, so
a malformed one there cannot affect it. Solo mode reads as before.
Search and preview use a cache private to that one request, under the project's
.private-reads/: nothing is read from or written to a cache other users
share, a returned file is read only from that request's cache (a regular file,
of its stated size and SHA-256), and the cache is removed when the request ends.
A cached listing (@jira:issues, @github:issues) and a cache-only read are
refused, since a shared cache holds what other users fetched. A server that
stops mid-request can leave that request's directory behind; nothing removes it
yet. The directory's file modes separate nothing between Hashd users, who share
the server's OS account: the boundary is that no shared read path reaches it.
Planning reads as the story's owner. The references a planning or PM
attempt captures for a story (its typed @connector: references and attached
items) are read with the account of whoever owns the story at that moment, so a
reassignment carries through to the next attempt. The read uses a cache private
to the attempt, as search and preview do; what it returns is copied into the
story's captured inputs and the cache is removed. A story with no owner, or an
owner with no usable account, fails the attempt with the reason and how to fix
it; nothing is read with the project's or the server's credentials instead.
Chat references are unavailable in team mode for these connectors:
@jira:KEY, @github:N, @azure:N, @clickup:ID, @confluence:ID and
@figma:NAME in a chat message are
refused, in every turn and when the conversation is rebuilt, and not read with
anyone's credential. What such a read returns is a file the agent reads on later
turns, and nothing yet keeps it with the conversation. Before this change chat
read them with the project's or the server's credentials; that stopped
deliberately. A bare @jira still lists the connector's tools. Preview an item,
or paste what the conversation needs.
Not yet covered (#1856):
- Chat references to the connectors above: keeping what they return with the conversation, and answering later turns and rebuilds from it.
- Connector caches written before this change, and by solo mode, are not purged; implementation still unfolds references from the shared caches.
- Autocomplete (
GET /connectors/autocomplete) still offers the issue keys in the project's shared Jira cache to every signed-in user, with or without an account. That is separate from the cached listings above:@jira:issuesand@github:issuesare refused under your own account, but the keys autocomplete enumerates are not. Reads made with your own account do not add to that cache. GET /projects/{name}/config/rawreturns the project'sconfig.yamlas written, including any connector credential in it, to every signed-in user.
Every client shows a connector from what it declares, the same way for every
connector, so no client and no part of core names one. The host loads and
checks these at discovery and serves them in capabilities, with no project:
-
DISPLAY_NAME: a short name ("Jira"). Without it, the connector's name. -
A
ConfigField'slabel: what a person reads ("Site URL", "Default project"); the key is whatconfig.yamlholds, and clients show it only where raw keys belong (Advanced). Without one, the host derives it from the key ("project_key" -> "Project key", "file_id" -> "File ID"). Write thedescriptionfor the person filling the field in. -
ICON_LIGHT/ICON_DARK: SVG files in the connector's own package, drawn on light and on dark backgrounds; either alone serves both. Clients draw them as images, never inline, so an icon cannot run script. A plain file name only. -
ABOUT: a markdown file in the package. Say what the connector does, what a person needs, and what it reads and writes. Clients render it without raw HTML. -
LOGIN_METHODS: the ways a person signs in to the destination. Each method's fields are one complete credential set, stored and handed to the connector under exactly those keys, so a connector'sCREDENTIAL_MODESshould be derived from it (the bundled ones are). Every method has at least onesecretfield; a secret is never shown back and never has an example. A field'spatternis a full-match regular expression a value must satisfy (ClickUp's personal token starts withpk_), checked before the account is stored; say it in words in the field'sdescription. Both languages apply it, so theCONFIG_FIELDSpattern rules hold here too: keep to the shared subset and add it topattern_samples.json. Ahelp_urlmust be https. A method withforge_loginoffers the person's forge login for the destination host instead of a credential of its own: it has one secret field, which is filled from the forge token when the connector is used, and it is offered only to someone with a forge login stored there; nothing of it is stored with the account. ItsACCOUNT_DESTINATIONmust answer a forge host. Because any connector can declare one, Hashd describes that method itself -- naming the connector and the host, and that the token can also push code and merge pull requests -- instead of showing the connector's own description. DeclaringLOGIN_METHODSis what gives a connector personal accounts: the server's account store, its CLI (hashd connector login) and the Web page all read them, and none names a connector. -
ACCOUNT_DESTINATION: required withLOGIN_METHODS, along with aCONFIG_FIELDSfield markeddestination. A function from what a person typed (a site URL, a workspace ID) to the destination their account is stored for. Applied to whatREMOTE_SCOPEreports, it must give the same answer: that is how an account is found for every project at that destination, and what the host checks before a personal credential is used. For most connectors the two are the same string; one account may also cover many scopes (GitHub: the host, for every repository on it). RaiseValueErrorwith a message written for the person on anything that is not a destination. It must be pure -- no network, no project -- because the server asks it whenever it resolves a destination (account_destinations, one host call for every connector asked about) and keeps the answers briefly. -
NOTES_MARKDOWN:Truewhen the comments itsSYNC_BACKENDposts render Markdown, so what Hashd adds to a note (an attribution) is escaped as Markdown there. -
CREATE_STORY(#2918): called with the project directory, it returns an object whosefind_or_create(story)finds the tracker story carryingstory.stamp, else creates it as the fixed view (TrackerStoryContract: title, problem, criteria, the line naming the hashd story and its link), and returns its native id and whether it created it. The host'screate_storyverb calls it behind the same gates as a write (MODIFIES_EXTERNAL, configured, a readable destination). Settings only creation needs declareneeded_for: create.
A stored account reaches the connector as the caller credential source:
HASHD_CONNECTOR_CREDENTIAL_SOURCE=caller and HASHD_CONNECTOR_CREDENTIALS, a
JSON object of credential field to value. A connector whose config loader uses
hashd_client.connector_env.resolve_connector_env gets exactly that set and no
credential from config.yaml or the environment; it needs no variable names of
its own for it. One whose tool reads its own credential (GitHub runs gh)
calls connector_env.caller_credentials and hands the tool exactly that set,
and never lets it fall back to a login on the machine. The server scrubs each
handed-over value from the host's output.
Files are capped at 16 KiB, and must ship in the package
([tool.setuptools.package-data]). An unusable declaration is logged and left
out rather than shown half-working. The package name and version come from the
distribution that provides the entry point.
| File | What |
|---|---|
cli.py |
Registers CLI commands from CLI_COMMANDS |
commands/doctor.py |
Runs DOCTOR_CHECKS for configured connectors |
lib/ref_resolver.py |
Dispatches @connector:ref to ARTIFACT_RESOLVER |
lib/agents_config.py |
Injects MCP config for TOOLS into agent commands |
server/api/autocomplete.go |
REST endpoint for TUI autocomplete (reads connector caches) |
A connector can act on committed Hashd facts about a story it is attached to.
It declares EVENT_HANDLER and EVENT_TYPES. A project then subscribes the
connector by name, in the connector's own section:
azure:
events:
subscribe: [requirements_approved, workstream_ready_to_merge]Nothing is sent until a project subscribes. Subscribing to events does not change notes: a milestone subscribed as an event is also still documented as a note, unless notes are switched off.
Types. These are the note milestones: requirements_approved,
story_edited, clarification_answered, workstream_ready_to_merge,
workstream_merged and workstream_pr_link. workstream_plan is a note
only, never an event: the plan a workstream's breakdown wrote, its
micro-commits as stored, posted when it is made and again only when a later
breakdown, whole or partial, replaces it, marked replacing. The
workstream_ready_to_merge note carries the final review as recorded: its
verdict and the reviewer's summary. A note is never cut; one the tracker
refuses is a failed note on the story, whole. Three more types are events
only, never notes:
story_implemented: the story reached implemented. This happens automatically once every workstream it owns has finished, or when an operator marks it implemented.story_abandoned: the story was closed, cancelled, or abandoned.workstream_started: the story's workstream moved into implementing for the first time. It is published once per workstream, and later returns to implementing publish nothing.
story_implemented and story_abandoned are terminal, so each happens at
most once per story. Unlike the workstream milestones, they speak for the
whole story. An unknown name is
ignored with a warning. A type the connector's EVENT_TYPES does not declare is refused at
delivery, and the refusal is recorded on the story.
Default tracker behavior. Subscription is still required. The default
work-start milestone is requirements_approved. Existing workstream_started
support and its connector mappings remain available. These defaults use the
existing lifecycle settings as overrides; no new keys are needed.
| Event | Azure Boards | ClickUp | GitHub Issues | Jira |
|---|---|---|---|---|
requirements_approved |
InProgress; override: azure.lifecycle.requirements_approved. Missing default category: successful no-op; ambiguous states require .states. |
Unchanged; override: clickup.lifecycle.<list id>.requirements_approved (to / from). |
Unchanged, no default label; override: github.lifecycle.labels.requirements_approved. |
No inferred move; an unmapped subscribed event is refused; add jira.lifecycle.requirements_approved (to / from). |
workstream_pr_link |
InProgress; override: azure.lifecycle.workstream_pr_link. Missing default category: successful no-op; ambiguous states require .states. |
Unchanged; override: clickup.lifecycle.<list id>.workstream_pr_link (to / from). |
Unchanged, no default label; override: github.lifecycle.labels.workstream_pr_link. |
No inferred move; an unmapped subscribed event is refused; add jira.lifecycle.workstream_pr_link (to / from). |
workstream_ready_to_merge |
Resolved; override: azure.lifecycle.workstream_ready_to_merge. Missing default category: successful no-op; ambiguous states require .states. |
Unchanged; override: clickup.lifecycle.<list id>.workstream_ready_to_merge (to / from). |
Unchanged, no default label; override: github.lifecycle.labels.workstream_ready_to_merge. |
No inferred move; an unmapped subscribed event is refused; add jira.lifecycle.workstream_ready_to_merge (to / from). |
workstream_merged |
Resolved; override: azure.lifecycle.workstream_merged. Missing default category: successful no-op; ambiguous states require .states. |
Unchanged; override: clickup.lifecycle.<list id>.workstream_merged (to / from). |
Unchanged, no default label; override: github.lifecycle.labels.workstream_merged. |
No inferred move; an unmapped subscribed event is refused; add jira.lifecycle.workstream_merged (to / from). |
story_implemented |
Completed; override: azure.lifecycle.story_implemented. Missing default category: successful no-op; ambiguous states require .states. |
Sole closed/done status; override: clickup.lifecycle.<list id>.story_implemented (to / from). Zero targets: successful no-op; several targets: refusal. |
Close as completed; override: github.lifecycle.close. Labels are optional via github.lifecycle.labels.story_implemented. |
No inferred move; an unmapped subscribed event is refused; add jira.lifecycle.story_implemented (to / from). |
story_abandoned |
Removed; override: azure.lifecycle.story_abandoned. Missing default category: successful no-op; ambiguous states require .states. |
Sole closed/done status, the same as implementation because ClickUp has no abandoned status type; override: clickup.lifecycle.<list id>.story_abandoned (to / from). Zero targets: successful no-op; several targets: refusal. |
Close as not planned; override: github.lifecycle.close. Labels are optional via github.lifecycle.labels.story_abandoned. |
No inferred move; an unmapped subscribed event is refused; add jira.lifecycle.story_abandoned (to / from). |
An equivalent default the tracker cannot express succeeds without a write;
an explicitly configured move that cannot be made is refused. In Azure, set
azure.lifecycle.<event>.states to select among several states in the target
category; an unavailable category named by an override is refused.
Moves go forward only, and finished items are never edited or reopened. Azure
ranks state categories; configured ClickUp moves and Jira rely on the operator's
from / to mapping to define progression. For an unmapped terminal event,
ClickUp uses the List's sole closed/done status by default. GitHub adds
milestone labels, never
removing or ranking them. Only the story's own terminal events finish an item;
a workstream milestone never does. Before terminal writes, including GitHub
labels, attachment_shared: "true" leaves the item alone, "false" permits
the action, and an absent or invalid fact is refused. The fact is a delivery
snapshot from this project's records, with the limits described below.
GitHub supplies no default labels: they belong to the repository and must
already exist there. An absent github.lifecycle.close enables both terminal
closes; an explicit list, including [], is authoritative. Compatibility:
a subscribed terminal event with a label and no close list now also closes;
close: [] preserves label-only behavior. Unmapped non-terminal events
succeed without edits. Jira retains its configured transition behavior and
infers no default move.
The event. The host verb is deliver_event. Each event carries:
type,occurrenceandoccurred_at(when it was published, just after the commit);- the story, the workstream, and the attached item (
external_id,connection_id); facts: the title, and the link where there is one.story_implementedandstory_abandonedalso carryattachment_shared:"true"when another story in this project, not yet implemented or abandoned, is attached to the same remote item (same connector,connection_idandexternal_id), and"false"when none is. It is absent when it could not be read; treat that as unknown, never as"false". It is read at delivery from this project's own records, so a story in another project attached to the same item is not seen. It does not guarantee anything once read: an attachment or transition after the read is not reflected. What to do with it is the connector's decision;actor: who caused it;credential: whose account the connector acts with.
Actor and credential are separate.
actoris a Hashd user (kind: userwithuser_id) orkind: system. It is never a guess. A user is the authenticated Hashd account that requested the action. It is not an independently verified person: a client that sends one shared account's token is reported as that account.- A workstream reaching ready to merge is caused by the system, and acted on
with the workstream owner's account (
credential.kind: owner). - A workstream starting implementation (
workstream_started) is caused by the system, and acted on with the workstream owner's account (credential.kind: owner), as for ready to merge. - A merge or a PR link that Hashd performed (
hashd merge,hashd pr create) is caused by the account that requested it. It is acted on with the workstream owner's account, as for ready to merge. - A story milestone is caused by the signed-in account, and acted on with that account. That includes an operator marking a story implemented or abandoning it.
- A story Hashd found implemented, once every workstream finished, is
attributed to the story's owner (
kind: userwith the owner's id) and acted on with the owner's account (credential.kind: owner). This records who is responsible for the story. It does not claim the owner performed any merge; each merge keeps its own attribution above. A story with no owner is withheld. - When nobody can be named as the cause, the event is withheld and the note
still goes out. That covers:
- a request with no authenticated account, including solo-mode loopback requests;
- a merge or PR link from an execution started before the requester was recorded;
- a merge Hashd only found done: a PR merged on the forge by somebody
else, or a merge finished by hand after conflicts. This holds even when
a
hashd mergewas waiting for it.
Credentials. credential names the account Hashd supplied to the
connector host for this delivery. It is the same account a note would use: in
team mode, the person's own connected account and never a fallback account; in
solo mode, the server's own login (credential.kind: server).
credential is not a guarantee of the remote identity a handler acts with.
Hashd hands the account only to the connector's own credential loading, so a
handler must build its client through that credential-aware loader, the same
way its write backend does. A handler that reads another token, file or
environment variable acts as whoever that belongs to, and Hashd cannot see or
prevent it.
Delivery.
- Checked with the same gates as outbound notes: a connector that is configured, declares that it modifies external systems, and still points at the attachment's destination.
- Each occurrence starts once and is delivered once to each subscribed attachment. It is never retried.
- Events are unordered: two facts about one story can arrive in either order, so a handler that changes state should be safe to apply in either order.
- A delivery that fails is recorded on the story. It is recorded as "not sent" when it was refused before the connector was reached, and as "not confirmed" when the connector may have acted.
- Hashd does not record what a connector did with an event.
resolve_refs() scans text for @connector:ref patterns, dispatches to the connector's ARTIFACT_RESOLVER, and replaces refs with file metadata. Resolution happens BEFORE any prompt reaches an agent.
There are two resolver implementations sharing the same connector-host surface:
- Python harness (
lib/ref_resolver.py) -- used by the planner and runner prompt assembly. Connector dispatch only; built-in artifact names inBUILTIN_REFSare skipped and resolve elsewhere. - Go server (
server/internal/refs/) -- used by the chat generation path (a chat session message, servinghashd chat, the TUI and the Web). One entry point unfolds every@-reference in place so the agent never sees a raw token: built-in artifacts load locally in Go from the project DB / git / filesystem, and connector references dispatch through the same connector host viaserver/internal/connectors. This is the Go-canonical home for server-side chat@-reference resolution.
Both call the identical connector-host verbs (capabilities, resolve_artifacts), so connectors plug into either resolver unchanged.
| Pattern | What happens |
|---|---|
@figma:job-list |
Resolves to cached file references (JSON, SVG, TXT) |
@github:42 |
Resolves to cached/fetched GitHub issue details |
@jira:PROJ-123 |
Resolves to cached/fetched Jira issue details |
@jira:123 |
Resolves using default project key from config |
@jira:OTHER:456 |
Resolves to OTHER-456 (cross-project) |
@figma (bare) |
Resolves to tool listing + cached artifacts manifest |
@diff, @story, etc. |
Built-in refs -- not routed to connectors |
Batch interface -- receives all refs for the connector at once:
def resolver(project_dir: Path, refs: list[str], fetch: bool) -> dict[str, ResolvedArtifact]:refs=[""]for bare@connectorfetch=True: check staleness, fetch on cache miss (interactive contexts)fetch=False: cache only, error if missing (batch stages)- Returns
ResolvedArtifactwith file references (path, format, size, description) or error - Never raises -- errors in the
ResolvedArtifact.errorfield - A tracker connector may also return
projection, anItemProjection: the item's type, state, revision, tags, display-onlyattributesin the tracker's own words, parent and childlinks, andfields, each aProjectedFieldholding one field converted to Markdown (whole, with the SHA-256 of its bytes) under a role:description,acceptance_criteria,repro_stepsorother. The connector maps its own facts into the neutral hintsstory_type_hint(featureorbug) andtarget_repo_hint. The contract names no tracker's concepts. Convert HTML withhashd_client.html_markdown.html_to_markdown, so every connector projects the same HTML to the same bytes; also write the Markdown as anmdfile infiles, which is what the planner reads.
Specific refs get file metadata:
@figma:job-list resolved to:
Source: Figma: Job List (375x812pt)
Figma source JSON: .cache/figma/frames/job-list.json (48KB)
SVG visual export: .cache/figma/frames/job-list.svg (14KB)
Structural text summary: .cache/figma/frames/job-list.txt (2KB)
Bare refs get tool listing + cached data:
@figma capabilities:
Available tools:
figma_browse(query) -- Browse Figma file pages and frames
figma_fetch(name) -- Fetch a specific Figma frame's cached file paths
Cached data:
Figma artifact listing: .cache/figma/listing.txt (245B)
Resolution failure triggers a human gate:
- Interactive: retry/continue/abort prompt. Continue allows optional user context.
- Non-interactive (
--yes): continues with missing-artifact note injected. - Prefect flows: transition to blocked state.
Same ref appearing multiple times: first occurrence gets full metadata, subsequent get (see @connector:ref above).
apply_substitutions() uses context-aware regex:
- Bare
@mockwon't match inside@mock:test(colon in negative lookahead) @figma:jobwon't match inside@figma:job-list(word/hyphen boundary)
@dataclass(frozen=True)
class ToolSpec:
name: str # globally unique, model-facing
description: str # one line, shown to the agent
parameters: dict[str, str] # param_name -> description; each an optional string
handler: Callable[[ToolContext, dict[str, str]], str]
@dataclass(frozen=True)
class ToolContext:
settings: dict[str, str] # the connector's effective settings (declared fields, never secrets)
account: dict[str, str] # the work owner's stored account; empty without LOGIN_METHODS
destination: str # where that account is for
cache_dir: Path # the connector's own cacheA handler uses only its context: it reads no project configuration, environment
variable or other login. Core and the connector host speak tool contract
version TOOL_CONTRACT_VERSION (1); a call at any other version is refused,
with no compatibility path.
Tools run on the server, in its connector host. An agent reaches them, wherever
it runs, through hashd's connector tool server (hashd-tools, hashd code connector-tools-mcp), which forwards with the run's token:
GET /connector-tools?project=<p>lists the tools the project's configured connectors declare.POST /connector-tools/call?project=<p>with{connector, tool, arguments}runs one. Only a declared tool, and only its declared parameters, are accepted.
The tool server holds no connector package and no connector credential, so a runner carries neither.
Tool failures injected as result text (not raised). Model is instructed to stop if the error is critical. Errors surfaced to human at next opportunity. Results truncated at 100KB.
Each connector gets a cache directory:
projects/hbc/.cache/<connector_name>/
The connector owns its cache layout. Core doesn't read it directly -- the ARTIFACT_RESOLVER manages the cache.
- Populate:
hashd <connector> importor fetch-on-miss - Refresh:
hashd <connector> syncor staleness check (profile-dependent) - Read:
ARTIFACT_RESOLVERreads from cache, returns file references - Inspect: files are plain text/JSON/SVG, human-readable
Connectors declare CACHE_STRATEGY to control workstream behavior:
"live"(default): always reads from the shared project cache. Used by GitHub and Jira (cheap API calls, data changes frequently)."snapshot": cache is frozen into the workstream ops dir at provisioning time. Implementation reads from the snapshot, zero API calls. Used by Figma on conservative/standard profiles (6 API calls/month on free tier).- Callable
(project_dir) -> str: dynamic strategy. Figma uses this to go live on aggressive (enterprise) profiles.
Snapshot is copied by snapshot_connector_caches() during provision_workstream(). The resolver reads from the workstream snapshot via contextvars without changing the ARTIFACT_RESOLVER interface.
server/internal/cli/connector_tools_mcp.go -- the stdio MCP server
(hashd-tools) through which an agent calls connector tools.
- Orchestrator writes MCP config before agent invocation (format varies per agent)
- Agent starts
hashd code connector-tools-mcp --project <p>as a stdio subprocess - On
tools/listit lists the project's tools from the server (GET /connector-tools) - On
tools/callit forwards the call (POST /connector-tools/call) and returns the result, or the server's refusal as an error result
| Agent | Config mechanism |
|---|---|
| Claude Code | --mcp-config flag with JSON file |
| Codex | .codex/config.toml in worktree |
| Gemini CLI | .gemini/settings.json in worktree |
| OpenCode | OPENCODE_CONFIG_CONTENT environment overlay (mcp key) |
| Kimi Code | --mcp-config-file flag with JSON file |
| Qwen Code | .qwen/settings.json in worktree |
File-based configs are excluded from git via .git/info/exclude.
A connector's tools act for the person who owns the work, in every mode: the owner the run's token recorded when the stage started (the workstream's, or the story's when there is no workstream), so a reassignment takes effect at the next stage. On a solo server unowned work is the server owner's.
- For a connector that declares
LOGIN_METHODS, the server runs the tool in a connector host handed only that person's stored account for the connector's destination, and pinned to it: the host refuses before the tool runs if the connector points elsewhere. A credential value in what the tool returns is replaced with[REDACTED]. - With no usable account (none stored, unowned team work, a declaration the host refused) the tool does not run, and the call is refused naming the sign-in command. Project configuration and environment credentials are never read instead. The stage itself is never refused for it.
- The agent never sees a connector credential: the account stays on the server.
In team mode, hashd posts a story note on a tracker only with the connected
account of the person the note speaks for. That is the signed-in user whose
action caused it (an approval, an edit, an answer), or the workstream's owner
for a workstream milestone (ready to merge, merged, PR link), whoever clicked.
It never uses the server's own gh login or environment, or the project's
connector credentials, for a note. Solo mode is unchanged. Commits, pushes and
PRs are unchanged.
-
GitHub issues, Jira, Azure Boards, ClickUp, and any connector declaring
LOGIN_METHODS: each user can connect a personal account for one destination on the connector's Web page, or withhashd connector login <connector> --destination <site, Workspace ID or organization> [--method NAME] [--field KEY=VALUE]..., and check or remove it withhashd connector status/logout.--methodpicks one of the connector's sign-in methods (asked on a terminal when it has several); fields that are not secret go in--fieldor are asked; the secret is read hidden or from stdin. It is stored encrypted and never shown again. A note on an item at that destination is posted with that account. The server hands it only to the connector for that one write, and the connector ignores every other credential in the project's config or the server's environment. With no account connected for the destination, the note is withheld unless the project chose a fallback account (below). -
GitHub issues signs in for a host (
github.com, or an Enterprise host) and the account covers every repository there. Two ways: an Issues token (a fine-grained token with Issues: Read and write, the safer choice, since it can do nothing else), or Use my forge login, offered only once you have stored one for that host (hashd forge login, Settings > Forge). The forge login is not copied: the account reads it when it is used, so rotating it carries through and removing it leaves the account unusable rather than falling back to anything else. It can do far more than issues need.hashd connector login github --destination github.com --method "Issues token" hashd connector login github --destination github.com --method "Use my forge login"
Change from earlier versions: GitHub issues. GitHub issues used to read
and post with your forge login automatically. It now has an account of its
own, like the other trackers: until you sign in to it (with an Issues token or,
by choice, your forge login), team-mode GitHub reads are refused, notes are
withheld, and hashd connector github check is refused in either mode. Solo
mode's reads and notes are unchanged. Its fallback accounts (below) now use destinations (hosts or
repository URLs, each standing for its host), not repositories, so one
approves every repository on a host.
Change from earlier versions. Team projects whose notes were posted with
the server's gh login or a project token now withhold those notes until the
user connects a GitHub account. For Jira, Azure Boards and ClickUp they are
withheld until the user connects an account for that destination. A note is also withheld when nobody is
identified: a request with no signed-in user, a workstream with no owner, or a
note queued before an upgrade. A withheld note is recorded on the story as
not sent, with the reason. The action that caused it still succeeds.
Fallback accounts are temporarily suspended. A project's choice of a fallback account, described below, is currently never honoured, for GitHub, Jira, Azure Boards and ClickUp alike. Each such note is recorded on the story as not sent, with the reason "Fallback accounts temporarily suspended". A person's own connected account is used exactly as before, and solo mode is unaffected. The central definitions and the project choices are kept as they are, and no configuration change is needed. They take effect again when fallback accounts are restored. The rest of this section describes how they work then.
Fallback accounts (optional, off by default). A team project can choose
an approved account to post a connector's notes for a person who has not
connected an account of their own for the destination, under that
connector's own section (github, jira, azure, clickup).
Defining an account (server administrators). Only a server administrator
defines fallback accounts, in the central config. This is the file
hashd config set writes, and it needs an owner or admin in team mode.
destinations: where the account may post, as the connector names its account destinations -- sites, organizations, Workspace IDs, or GitHub hosts (a repository URL stands for its host).- The credential is one complete set of the connector's own sign-in fields. A
field that only identifies the account (Jira's
email) is written as a value. Every secret is written only as<field>_env, naming the server's environment variable that holds it:token_env,api_token_env,pat_envoraccess_token_env. A secret written as a value is refused, and neither file ever holds one.
jira:
outbound_notes:
fallback_accounts:
hashd-automation:
label: Hashd automation # the name the note gives for who posted it
destinations: [https://example.atlassian.net]
email: hashd-bot@example.com
api_token_env: HASHD_NOTES_JIRA_TOKEN # or pat_env, for Server/DC
github:
outbound_notes:
fallback_accounts:
hashd-automation:
label: Hashd automation
destinations: [github.com]
token_env: HASHD_NOTES_GITHUB_TOKENChoosing one (a project). A project opts in by name in its own config, for
example jira.outbound_notes.fallback: hashd-automation. A project cannot
define an account itself, name a different environment variable, or send an
account's credential anywhere else.
The rules:
- The person's own connected account is always used first.
- The fallback posts only when that person has no account for the destination, and only to a listed destination.
- It is never used when the person's account cannot be read (a chosen forge login that is gone included) or the tracker rejects it, when nobody is identified, when the choice or definition is incomplete, or when the variable is unset. Each of these records the note as not sent, or not confirmed, with the reason.
- The note ends with "Posted by on behalf of , who has not
connected their own account to Hashd". Where the connector's comments render
Markdown (its
NOTES_MARKDOWN: GitHub, Azure Boards) the name is escaped as Markdown; elsewhere it is printed plain, and characters Jira's wiki markup would act on are left out. Ordinary punctuation is kept.
GitHub issue reference resolver. Use @github:42 in stories, acceptance
criteria, or chat to embed issue context. The connector reads issue details on
demand and caches them; it does not run a sync daemon. hashd story link STORY-x with no reference finds or creates the story's issue: it looks in
github.repo for issues, open or closed (pull requests excluded), labelled
hashd:<project>:<STORY-x>. One is linked; two or more are refused, each
named. Otherwise the label is created if it is missing, and one issue is
created with the story's title, a body holding the problem, the acceptance
criteria and the "Created by hashd" line (a link to the story unless
github.link_back is "false" or hashd's web.public_url is localhost),
and the stamp label, then linked as @github:<n>. Its remote writes are that
created issue and its label, hashd's outbound story notes -- a comment or a
pull-request link on an issue already attached to a story -- and, only for the
lifecycle events a project subscribes it to, an optional mapped label on that
issue (connector events, above), and default closing on the story's own
story_implemented (completed) and story_abandoned (not planned) events,
never while another story in this project still in progress shares the issue.
An explicit github.lifecycle.close list overrides the defaults, including
[] to disable closing. A subscribed terminal event with a label and no close
list now also closes; close: [] preserves label-only behavior. There are no
default labels, and unmapped non-terminal events succeed without edits. All but
the created issue and its label are refused unless the configured repository
is still the one the issue was attached from.
It never reopens an issue or removes a label.
See packages/hashd-connector-github/src/hashd_connector_github/README.md.
Design context integration. Import frames, reference in stories/ACs/chat, browse via tools.
See packages/hashd-connector-figma/src/hashd_connector_figma/README.md.
Jira issue reference resolver for Jira Cloud (REST API v3) and Server/Data
Center (REST API v2). Use @jira:PROJ-123, @jira:123, or
@jira:OTHER:456 in stories, acceptance criteria, or chat to embed issue
context. The connector reads issue details on demand and caches them; it does
not create hashd stories or run a sync daemon. Besides the issue
hashd story link creates (below), its remote writes are hashd's outbound
story notes (a comment or a pull-request link) and, opt-in, a status move for a
subscribed event mapped in jira.lifecycle. Notes and moves act only on an
issue already attached to a story, refused unless jira.url is still the site
the issue was attached from. Only the story's own terminal events
(story_implemented, story_abandoned) may move an issue to a status in Jira's
done category, and not while attachment_shared says another unfinished story
still uses it; nothing reopens an issue. See
Lifecycle moves.
hashd story link STORY-xxx PROJ-123 links a story to an existing Jira issue,
and hashd story link STORY-xxx finds the issue labelled for it in
jira.project_key or creates one of type jira.issue_type; see "Tracker
stories" in WF.md.
See packages/hashd-connector-jira/src/hashd_connector_jira/README.md.
Read-only Cloud page artifacts via @confluence:123456 on the configured site.
Typed full URLs are unsupported by current shared input parsing. Bundled but
unconfigured; use the existing project configuration editors.
Raw JSON/storage and a readable projection retain current content and report
conversion limitations. See the provider guide
for token routes, tenant-verification limits and configuration. No connector CLI.
In team mode each person reads Confluence with their own account for the site
(hashd connector login confluence --destination https://SITE.atlassian.net,
or its Web page): their Atlassian email and an API token.
Azure DevOps Services work items use @azure:123 or the shared reference picker.
Search stays within the configured organization/project, or the projects
azure.intake.sources names in that organization; native state, assignee and
type filters preserve Azure values, and area path, iteration, tag, team,
changed_since and saved-query filters scope the listing to the team's board,
with azure.intake setting the picker's defaults. Explicit numeric references can read any
work item accessible to the credential within that organization, including other
projects. The configured project limits search, not direct-ID access; Azure
credential permissions and existing Hashd caller/project authorization still apply.
Full returned JSON reaches preview and
the same owned planning capture as typed references. Related targets and history
are not implicitly fetched, and there are no ownership claims. The only remote
writes include outbound notes on attached items and forward-only state moves on
events subscribed through azure.events.subscribe. By default,
requirements_approved and workstream_pr_link target InProgress,
workstream_ready_to_merge and workstream_merged target Resolved,
story_implemented targets Completed, and story_abandoned targets Removed.
An explicit azure.lifecycle.<event> entry replaces its default and retains
category and state validation; workstream_started requires such an entry.
A missing category succeeds without a write only for a default; several states
require a choice in azure.lifecycle.<event>.states even for a default.
Finished items are never touched. Only a story's own terminal events finish an
item, and only when attachment_shared is "false": "true" leaves it alone,
while an absent or unknown fact refuses the terminal move. The fact covers
other stories still in progress in this project.
hashd story link STORY-xxx 1234 links a story to an existing Azure DevOps
story, hashd story link STORY-xxx finds the work item tagged for it in
azure.project or creates one of type azure.work_item_type, and
hashd story unlink STORY-xxx removes the link in hashd only; see "Tracker
stories" in WF.md.
Use the existing project configuration editors with exactly one PAT or externally
supplied Entra access token. Ordinary authorized config readback remains unchanged,
not masked secret storage. See the provider guide.
Azure Boards permission selection follows the operation, including POST reads:
| Boards operation | Required resource-prefixed permission | Retained grant satisfying it |
|---|---|---|
| Item/reference reads; fields, types, states and team settings; saved-query definition/execution; WIQL, batch and search POSTs; story-stamp lookup | 499b84ac-1321-427f-aa17-267ca6975798/vso.work |
499b84ac-1321-427f-aa17-267ca6975798/vso.work_write inherits Work read |
| Work-item creation/updates, comments, PR relations and lifecycle state changes | 499b84ac-1321-427f-aa17-267ca6975798/vso.work_write |
Work write directly |
| Azure Repos PR lookup before adding an artifact relation | 499b84ac-1321-427f-aa17-267ca6975798/vso.code |
499b84ac-1321-427f-aa17-267ca6975798/vso.code_write inherits Code read |
An explicit Bearer insufficient_scope response names the failed operation's
permission, the retained write grant and its read inheritance. Have a tenant
administrator configure that grant in the supplying app's Azure DevOps delegated
permissions and grant administrator consent. Then obtain a replacement token from
the external supplier and store it for the selected connector destination:
hashd connector login azure --destination https://dev.azure.com/your-organizationChoose the Entra access-token credential and retry the failed operation manually.
This updates the connector account; hashd forge login uses a separate account
and cannot renew it. In a configuration/environment credential route, replace
that route's effective azure.access_token or AZURE_DEVOPS_ACCESS_TOKEN instead;
clear a displaced environment override when the configured value should win.
hashd connector azure status shows the destination, and
hashd connector azure configure corrects it. PATs retain their existing Basic
credential and Work Items/Code permission guidance. A plain 403 leaves
project/item authorization and token permissions uncertain; expiry and
connectivity failures keep their own diagnoses. Rejection bodies and challenges
may echo a credential and are not copied into diagnostics.
ClickUp tasks use native task IDs such as @clickup:86a4xte6z, or the shared
reference picker, which browses the configured List with ClickUp's native paging
and exact status, assignee, tag and updated-since filters. ClickUp has no native
task text search; picker text is an exact task ID lookup. Custom Task IDs and
URLs are not accepted. Every read verifies the returned Workspace against
clickup.workspace_id; explicit task IDs can name any task that token can read in
that Workspace, including other Lists. Full returned task JSON reaches preview and
the same owned planning capture as typed references. Comments, attachment files
and Docs are not fetched; there are no ownership claims. Its remote writes are
tracker task creation, hashd's outbound story notes (a comment or a pull-request link) and, opt-in, a
status move for a subscribed event. An unmapped story_implemented or
story_abandoned moves any open/custom task to its List's sole closed/done
status; no terminal status leaves it unchanged and succeeds. Several terminal
statuses refuse before writing: configure clickup.lifecycle.<list id>.<event>
with to and from to choose. A configured List/event move replaces the
default, resolves names ignoring case, and only moves from its named from
statuses to to. Other unmapped events succeed without a move. Notes and status moves
act only on a task already attached to a story, refused unless
clickup.workspace_id is still the Workspace the task was attached from. Only
the story's own terminal events (story_implemented, story_abandoned) may
move a task to a closed or done status, and not while attachment_shared says
another unfinished story still uses it; nothing reopens a task.
hashd story link STORY-xxx 86a4xte6z links a story to an existing ClickUp
task, hashd story link STORY-xxx finds the task tagged for it in clickup.list_id
or creates one in clickup.list_id, and hashd story unlink STORY-xxx removes
the link in hashd only; see "Tracker stories" in WF.md.
Use the existing project configuration editors with exactly one personal token or
externally supplied OAuth access token. Ordinary authorized config readback remains
unchanged, not masked secret storage. See the provider guide.
Same connector contract, different API clients.
Discovery is Python-only (Neovim model). A Rust/Go connector works via a thin Python shim that delegates to a binary via subprocess or IPC. If we accumulate enough non-Python connectors, add a standardized wire protocol (msgspec-RPC, JSON over stdin/stdout) so shims become generic.
Step-by-step guide to building a new connector. Uses a hypothetical "Linear" connector as the example.
packages/hashd-connector-linear/src/hashd_connector_linear/
__init__.py
# packages/hashd-connector-linear/src/hashd_connector_linear/__init__.py
CONNECTOR_NAME = "linear" # unique -- becomes @linear:ref namespace
CONFIG_SECTION = "linear" # config.yaml section
CACHE_DIR_NAME = "linear" # .cache/linear/That's the minimum. hashd discovers it, hashd doctor shows it, @linear is reserved. Everything else is optional.
# packages/hashd-connector-linear/src/hashd_connector_linear/config.py
import msgspec
from orchestrator.lib.project_loader import load_project_yaml
class LinearConfig(msgspec.Struct):
api_key: str = ""
team_id: str = ""
def load_linear_config(project_dir):
raw = load_project_yaml(project_dir)
section = raw.get("linear", {})
return msgspec.convert(section, LinearConfig)
def is_configured(project_dir):
try:
config = load_linear_config(project_dir)
return bool(config.api_key and config.team_id)
except Exception:
return FalseWire it up:
# __init__.py (add)
from hashd_connector_linear.config import is_configured
IS_CONFIGURED = is_configured# __init__.py (add)
def _check_health(project_dir):
from hashd_client.connectors import DiagnosticResult
from hashd_connector_linear.config import load_linear_config
config = load_linear_config(project_dir)
results = []
if not config.api_key:
results.append(DiagnosticResult("Linear config", False,
"linear.api_key is empty\n"
" set it: hashd project config set linear.api_key <key>"))
return results
# ... API health checks ...
results.append(DiagnosticResult("Linear auth", True, "authenticated"))
return results
DOCTOR_CHECKS = [_check_health]# __init__.py (add)
def _resolve(project_dir, refs, fetch):
from hashd_client.connectors import ResolvedArtifact, ArtifactRef
from hashd_client.connectors import get_connector_cache_dir
cache_dir = get_connector_cache_dir(project_dir, "linear")
cache_dir.mkdir(parents=True, exist_ok=True)
results = {}
for ref in dict.fromkeys(refs):
# ... fetch/cache issue, build ResolvedArtifact ...
pass
return results
ARTIFACT_RESOLVER = _resolveNow @linear:LIN-42 resolves in prompts, chat, stories, ACs.
# packages/hashd-connector-linear/src/hashd_connector_linear/commands.py
def register_linear_subcommands(subparsers):
p = subparsers.add_parser("linear", help="Linear integration")
# ... add subcommands ...
return p
def cmd_linear_dispatch(args, ops_dir, project_config):
# ... dispatch subcommands ...
return 0# __init__.py (add)
from hashd_connector_linear.commands import register_linear_subcommands, cmd_linear_dispatch
CLI_COMMANDS = {"linear": (register_linear_subcommands, cmd_linear_dispatch)}from hashd_client.connectors import ToolSpec
TOOLS = [
ToolSpec(
name="linear_search",
description="Search Linear issues by text",
parameters={"query": "Search text"},
handler=_handle_search,
),
]Tools are exposed to agents via MCP (agent stages) and prompt-based dispatch (hashd chat).
def _autocomplete(project_dir, partial):
return [("issues", "Issue listing")] # extend with cached data
AUTOCOMPLETE = _autocompleteThe AUTOCOMPLETE function is called server-side by Python (Prefect flows, MCP server). The TUI and other remote clients get the equivalent via a separate REST endpoint (GET /connectors/autocomplete) that reads the connector's cache directory on the server.
All connectors are discovered via the hashd.connectors entry point group. Register an entry point for your connector package, including workspace-local packages:
# your-package/pyproject.toml
[project.entry-points."hashd.connectors"]
linear = "your_package.linear"CACHE_STRATEGY = "snapshot" # or "live" (default), or callableWithout writing any integration code in core:
hashd doctorvalidates your config and runs your health checks@linear:refresolves in every prompt surface- Your tools appear in MCP and chat
- Autocomplete works in TUI and CLI
- Cache snapshots work at provisioning time (if strategy="snapshot")
- Your connector is removable: delete the directory, everything else keeps working
- Inbound changes. Resolved: no automatic inbound sync. Operators reference external artifacts on demand with
@connector:ref. - Safety flags.
MODIFIES_EXTERNALnow gates the connector host'ssync_applywrites (outbound story notes).modifies_code, and gating autonomous execution on either flag, remain deferred. - TOOLS_ALWAYS_LOAD. Provision for tools that load on every invocation regardless of
@refs (e.g., a linter). No use case yet. - Plugin architecture. Rename "connector" to "plugin"? Event handlers vs daemons? Lifecycle hooks? Third-party sandboxing? Revisit when community connectors emerge.