The 'prompt' URI Scheme for AI Agent Sessions and Prompts

3.1. Scheme Name

The scheme name is prompt. It SHALL be written in lowercase in all generated URIs. Implementations processing incoming URIs SHOULD treat the scheme name as case-insensitive per [RFC3986] Section 6.2.2.1.¶

3.2. Complete ABNF

The following grammar, expressed in Augmented Backus-Naur Form [RFC5234], defines the syntax of a prompt URI. Terms not defined here are imported from [RFC3986] (unreserved, pct-encoded, host, sub-delims) and [RFC3339] (date-time).¶

prompt-URI    =  "prompt:" hier-part
                 agent-name "/" session-ref "/" prompt-ref

hier-part     =  "//" authority "/"   ; remote: authority-based
               / "/"                  ; local-only resolution

authority     =  [ userinfo "@" ] host [ ":" port ]
                 ; host: hostname or IP-literal (RFC 3986 s3.2.3)
                 ; userinfo: optional username
                 ; port: optional; default port is 7560

userinfo      =  1*( unreserved / pct-encoded / sub-delims )
                 ; Username identifying the user at the remote host;
                 ; the "user:password" form of RFC 3986 s3.2.1 is
                 ; NOT RECOMMENDED -- use username only

host          =  <host as defined in RFC 3986 Section 3.2.3>
                 ; DNS hostname, IPv4 address, or IP-literal

port          =  *DIGIT
                 ; decimal; absent port defaults to 7560

agent-name    =  1*agent-char
agent-char    =  unreserved / pct-encoded / "+" / "."

session-ref   =  session-id / session-alias
                 ; parsers cannot distinguish the two forms;
                 ; the distinction is semantic (Sections 4.4, 4.6)

session-id    =  1*( unreserved / pct-encoded )
                 ; Typically a UUID per RFC 9562

session-alias =  1*( unreserved / pct-encoded )
                 ; Special characters including SP (U+0020) MUST be
                 ; percent-encoded per [RFC3986] -- see Section 4.6

prompt-ref    =  date-time / prompt-id
                 ; RFC 3339 timestamp or a prompt identifier;
                 ; date-time always begins with a 4-digit year, so
                 ; the "~" prefix of prompt-id is unambiguous
                 ; See Sections 4.5 and 4.7

date-time     =  <date-time as defined in RFC 3339, Section 5.6>
                 ; Colons within date-time are valid in URI path
                 ; segments per RFC 3986 Section 3.3
                 ; Example: 2026-07-07T16:45:23.856Z

prompt-id     =  "~" 1*( unreserved / pct-encoded )
                 ; Agent-internal prompt correlation identifier;
                 ; "~" (U+007E, unreserved, RFC 3986) distinguishes
                 ; prompt-id from date-time in all syntactic contexts
                 ; Example: ~abc123, ~promptId%3Axyz

The following prompt URIs illustrate the syntactic forms. The first two use local-only resolution (single slash, no authority); the remaining three use remote resolution via a named host:¶

; NOTE: Lines ending with '\' are folded per [RFC8792].
;       No whitespace is implied at the fold point.

; Local-only forms (prompt:/ -- single slash, no authority)
prompt:/claude-code/\
  5674b542-0b94-4d12-bc05-d271a4131354/2026-07-07T16:45:23.856Z
prompt:/claude-code/5674b542-0b94-4d12-bc05-d271a4131354/~abc123

; Remote forms (prompt:// -- authority present)
prompt://mcp.example.com/claude-code/\
  5674b542-0b94-4d12-bc05-d271a4131354/~abc123
prompt://kboone@mcp.example.com/claude-code/\
  5674b542-0b94-4d12-bc05-d271a4131354/~abc123
prompt://mcp.example.com/claude-code/\
  md-csv-mcp%20design/2026-07-07T16:45:23.856Z

Breaking the local prompt-id form into components:¶

prompt-URI  = "prompt:"
              "/"  ; hier-part: local-only (single slash)
              "claude-code"  ; agent-name
              "/"
              "5674b542-0b94-4d12-bc05-d271a4131354"  ; session-id
              "/"
              "~abc123"  ; prompt-ref: prompt-id form

Breaking the remote form with username into components:¶

prompt-URI  = "prompt:"
              "//"  ; hier-part: remote resolution
              "kboone"  ; userinfo (username)
              "@"
              "mcp.example.com"  ; host (agent client machine)
              "/"
              "claude-code"  ; agent-name
              "/"
              "5674b542-0b94-4d12-bc05-d271a4131354"  ; session-id
              "/"
              "~abc123"  ; prompt-ref: prompt-id form

Breaking the remote alias form into components:¶

prompt-URI  = "prompt:"
              "//"  ; hier-part: remote resolution
              "mcp.example.com"  ; host (no username)
              "/"
              "claude-code"  ; agent-name
              "/"
              "md-csv-mcp%20design"  ; session-alias (%20 = space)
              "/"
              "2026-07-07T16:45:23.856Z"  ; prompt-ref: timestamp

3.3. Authority Component (Optional)

The authority component is OPTIONAL. Its presence is signaled by the double-slash // prefix following the scheme (prompt://), in accordance with [RFC3986] Section 3. When the authority is absent, the URI uses a single slash (prompt:/) and is resolvable only through a local MCP server instance.¶

When present, the authority takes the form:¶

[ username "@" ] host [ ":" port ]

The host subcomponent identifies the network host where the agent client application resides and operates on behalf of the user. The agent may reside in the cloud (such as Claude Code or GitHub Copilot), but this is the user machine where the agent's client application stores logs and session data that enable prompt resolution. The host MAY also provide an HTTP endpoint where an MCP server is accessible, enabling remote resolution of the URI over the network. It follows the host syntax of [RFC3986] Section 3.2.3 (DNS name, IPv4 address, or IP-literal).¶

The port subcomponent is OPTIONAL. When present, it is separated from the host by a colon (:), as defined in [RFC3986] Section 3.2.3. When absent, the port defaults to 7560, which is the registered default port for the prompt-scheme MCP server reference implementation.¶

The username subcomponent is OPTIONAL. When present, it is separated from the host by an @ (U+0040) character, following the same convention as HTTP and other URI schemes ([RFC3986] Section 3.2.1). It identifies the user account or identity principal under which the agent session log is stored at the remote host, and MAY be used by the remote MCP server to scope its session log search.¶

The agent-name is NOT part of the authority; it is always the first segment of the path (Section 3.4).¶

3.4. Path Component

The path component SHALL consist of exactly three segments separated by slashes:¶

1. The agent name (Section 4.4) -- identifies the software agent that generated the URI.¶
2. A session reference -- either a session identifier (Section 4.5) or a registered session alias (Section 4.7).¶
3. A prompt reference -- either an RFC 3339 timestamp (Section 4.6) or a prompt identifier (Section 4.8).¶

The path MUST begin with a slash. All three segments MUST NOT be empty.¶

3.5. Query and Fragment Components

This specification does not define semantics for query (?) or fragment (#) components. Implementations MAY append a fragment to a prompt URI as an implementation-specific disambiguation hint (see Section 8), but SHALL NOT rely on fragment processing in interoperable contexts. The query component SHOULD NOT be used; its presence does not affect identity or comparison.¶

4.1. Remote vs. Local Resolution

A prompt URI selects its resolution mode by the presence or absence of the authority (//host) prefix:¶

• Remote (prompt://[user@]host/...) -- The double-slash signals that an authority is present. The URI is intended to be resolved by contacting the prompt-scheme MCP server running at host over the network. This form is appropriate for sharing prompt references across machines, teams, or systems where the originating session log is accessible through a web-facing MCP endpoint.¶
• Local-only (prompt:/...) -- The single slash signals that no authority is present. The URI is resolvable only by a local MCP server instance that has access to the originating agent's session logs on the same machine. This form is appropriate for provenance records that will only ever be resolved on the machine that generated them.¶

Implementations that generate prompt URIs SHOULD choose the local form by default and SHOULD allow the user or configuration to specify a remote host when a web-accessible MCP server is available. Implementations SHOULD NOT silently upgrade a local URI to a remote one; the resolution mode is part of the URI's identity.¶

4.2. Host

The host subcomponent identifies the network host where the agent client application resides and operates on behalf of the user. The agent may reside in the cloud (such as Claude Code or GitHub Copilot), but this is the user machine where the agent's client application stores logs and session data that enable prompt resolution. It follows the host production of [RFC3986] Section 3.2.3. The host MAY also provide an HTTP endpoint where a prompt-scheme MCP server is accessible, enabling remote resolution of the URI over the network. A single MCP server MAY host resolution for multiple AI agents.¶

Host names SHOULD be stable DNS names. IP addresses SHOULD be avoided in long-lived provenance records because they are subject to renumbering.¶

The optional port number, when present, identifies the TCP port on which the prompt-scheme MCP server listens at that host. When absent, the port defaults to 7560, the default port of the reference implementation. When an explicit port number equal to 7560 is present, it is equivalent to the form with no port for comparison purposes (Section 5).¶

4.3. Username

The username is the OPTIONAL userinfo subcomponent of the authority. When present, it identifies the user account or identity principal whose agent session logs are stored at the remote host. The remote MCP server MAY use it to scope its session log search to that user's log partition.¶

The username is meaningful only when the authority is present (remote form). It SHOULD be omitted in local-only URIs, and SHOULD be omitted in remote URIs when the MCP server does not partition logs by user.¶

Two prompt URIs that differ only in the presence or absence of a username, or in the value of the username, are NOT equivalent (Section 5) unless the resolver determines that both usernames map to the same identity principal.¶

4.4. Agent Name

The agent name is the first segment of the path. It identifies the software agent that generated the URI. It is NOT a globally registered identifier; implementations SHOULD use a stable, recognizable short name (e.g., claude-code, github-copilot, cursor). Agents operated by different organizations SHOULD use distinct names to avoid collision.¶

The agent name MAY include a dot-separated hierarchy for namespacing (e.g., anthropic.claude-code), but this structure carries no defined semantics in this specification.¶

The agent name SHALL remain constant across all sessions and versions of a given agent implementation. Including a version number in the agent name is NOT RECOMMENDED, as it would render URIs from different versions incomparable even when they refer to the same logical agent.¶

4.5. Session Identifier

The session identifier SHALL be an opaque string assigned by the agent at session initiation. Implementations SHOULD use a UUID [RFC9562] for the session identifier to minimize collision probability across agents and deployments. UUID version 7 [RFC9562] is RECOMMENDED over version 4 because its monotonically increasing structure supports chronological ordering of sessions.¶

The session identifier SHALL be consistent throughout a session and SHALL NOT change during a session's lifetime.¶

4.6. Timestamp

The timestamp SHALL be formatted as an RFC 3339 [RFC3339] date-time value and SHALL use UTC (the Z suffix). The timestamp records the wall-clock time at which the tool call generating the URI was executed.¶

Implementations SHOULD include sub-second precision (milliseconds) in the timestamp to reduce the probability of within-session collisions (see Section 8). A timestamp with second-level precision is REQUIRED; millisecond precision is RECOMMENDED; microsecond precision MAY be used.¶

The timestamp is NOT the time at which the originating prompt was submitted. It is the time at which the tool call was executed. For a given prompt, multiple tool calls MAY be executed, potentially spanning multiple seconds. Each tool call produces a URI with its own timestamp; all such URIs are considered to refer to the same prompt for resolution purposes (see Section 6).¶

When the agent maintains an internal prompt correlation identifier, the canonical form of the URI SHOULD use that identifier in place of the timestamp (see Section 4.8).¶

4.7. Session Aliases

A session alias is a human-readable string that a user or implementation MAY register as an alternative to the session identifier in a prompt URI. Aliases improve legibility: prompt:/claude-code/md-csv-mcp-design/... is more immediately meaningful than prompt:/claude-code/5674b542-.../....¶

Registration: Aliases SHALL be registered in a local alias registry that maps each alias to the session identifier it represents. An alias is scoped to a single agent name and MUST map to exactly one session within that agent's registry. A session MAY have more than one alias registered to it.¶

Attempting to register an alias that is already registered to a different session SHALL be rejected with a conflict error. Attempting to register an alias that is already registered to the same session is idempotent and SHALL succeed without modifying the registry.¶

Case insensitivity: Alias lookup SHALL be case-insensitive. The alias MD-CSV-MCP-Design, md-csv-mcp-design, and Md-Csv-Mcp-Design MUST all resolve to the same session. Implementations SHOULD store aliases in normalized lowercase and normalize incoming aliases to lowercase before lookup.¶

Canonical URI form: In a prompt URI, an alias SHALL appear in its canonical URI form, which is the percent-encoded representation of the alias string with all characters encoded per [RFC3986] as required.¶

Handling of spaces and special characters: Spaces (U+0020) and any other characters not permitted in a URI path segment by [RFC3986] MUST be percent-encoded in the canonical URI form of an alias. The alias md-csv-mcp design is canonically encoded as md-csv-mcp%20design in a prompt URI. Hyphens and spaces remain distinct: the alias md-csv-mcp design and the alias md-csv-mcp-design are different aliases and resolve to different sessions (if both are registered).¶

Implementations that accept prompt URIs as input MAY repair aliases containing unencoded special characters by applying percent-encoding before lookup, in the same manner that web browsers correct malformed URIs.¶

Implementations MUST preserve the original human-readable alias string (as supplied at registration time, before percent-encoding) in the alias registry. This allows the original label to be displayed in user interfaces without loss of information.¶

Alias persistence: Alias registries are implementation-defined and may not persist indefinitely. Agents are not required to maintain alias registries across restarts, updates, or deployments. Users and systems requiring long-term, portable provenance references SHOULD use the session-identifier form of the prompt URI rather than the alias form, since session identifiers are generated by the agent and stored in its session log independently of any alias registry. Prompt URIs using an alias remain valid provenance references as long as the alias registry is intact, but are subject to becoming unresolvable (Section 6.3) if the registry is lost or unavailable.¶

Alias-to-session-id URIs: When a session has both a registered alias and a session identifier, both forms of prompt URI are valid and refer to the same session. Implementations MAY use the alias form in newly generated provenance records when an alias is registered, as it improves human readability.¶

4.8. Canonical Prompt URI

A prompt URI is canonical if its prompt-ref component is the most specific and stable identifier available for the prompt it represents. The canonical form determines which URI SHOULD be stored in provenance records.¶

Prompt identifier form (preferred): When the agent maintains an internal correlation identifier for each prompt (for example, promptId in Claude Code session logs [CLAUDE-SESSIONS] or interactionId in Copilot session logs [COPILOT-SESSIONS]), the canonical URI SHOULD use the prompt-id form (Section 3.2) with a leading ~ character:¶

prompt:/claude-code/5674b542-0b94-4d12-bc05-d271a4131354/~abc123

A canonical prompt-id URI uniquely identifies the prompt regardless of when tool calls execute within the prompt's processing. Because all tool calls from the same prompt share the same prompt identifier, two prompt-id URIs with the same session-ref and prompt-id components can be detected as equivalent by string comparison, without consulting the session log.¶

Timestamp form (fallback): When no prompt identifier is available, the canonical URI SHOULD use the timestamp at which the originating prompt was submitted by the user -- not the timestamp of any particular tool call within the prompt's processing. An implementation that records prompt-submission timestamps MAY use that timestamp in the canonical URI even if individual tool calls use their own tool-call timestamps (Section 4.6).¶

Tool-call timestamp URIs (those generated at the time a tool call executes) are valid provenance references but are not canonical: multiple such URIs from the same prompt are not equivalent by comparison (Section 5), even though they resolve to the same prompt (Section 6).¶

Normalizing to canonical form: Implementations SHOULD normalize all prompt URI references for a given prompt to the canonical URI before writing provenance records. Normalizing to the prompt-id form, when available, enables deduplication of provenance entries across the tool calls of a single prompt without requiring session log access.¶

6.1. Resolution Algorithm

Resolution is the process of mapping a prompt URI to one or more candidate prompts in an agent's session log. Resolution is OPTIONAL; a prompt URI is valid and useful as a provenance reference even when the referenced session log is unavailable.¶

A conformant resolver SHALL apply the following steps:¶

1. Parse the prompt URI and determine the resolution mode (Section 4.1):¶

   • Remote (prompt://...): extract host, username (if present), agent-name, session-ref, and prompt-ref. Contact the MCP server at host to perform steps 2-7 on the remote server. If username is present, pass it to the remote server so that it MAY scope its session log search.¶
   • Local-only (prompt:/...): extract agent-name, session-ref, and prompt-ref. Perform steps 2-7 using the local session log store.¶

   If session-ref is an alias, resolve it per Section 6.2 to obtain the session identifier before proceeding.¶

2. Locate the session log associated with the session identifier for the agent identified by agent-name. If resolving remotely and a username is present, the resolver MAY restrict its search to session logs owned by or accessible under that identity principal. If no matching log is accessible, the URI is unresolvable (Section 6.3).¶

3. If prompt-ref is a prompt-id (begins with ~): strip the ~ prefix, percent-decode the remainder, and locate all session log entries whose prompt correlation identifier matches. If exactly one entry is found, the URI resolves to that prompt. Proceed to step 5.¶

   If prompt-ref is a date-time: identify the most recent human-authored prompt entry in the session log whose recorded timestamp is on or before the URI timestamp. Because a single prompt may drive multiple agent actions -- file writes, commits, and pushes -- before the URI timestamp is captured, the elapsed time between the prompt and the URI timestamp may be substantial.¶

4. From the candidate entries, identify those that are prompt-type entries (user messages that initiated a turn), as opposed to tool call or response entries.¶
5. If exactly one prompt-type candidate is found, the URI resolves to that prompt.¶
6. If multiple prompt-type candidates are found, the URI is ambiguous (Section 8). The resolver SHOULD report all candidates and SHOULD NOT silently select one.¶
7. If the session log records an agent-internal correlation identifier (e.g., promptId in Claude Code session logs [CLAUDE-SESSIONS], interactionId in Copilot session logs [COPILOT-SESSIONS]), implementations MAY use that identifier to narrow candidate selection to a single result.¶

6.2. Alias Resolution

When the session-ref component of a prompt URI does not parse as a UUID and is not otherwise recognizable as a session identifier, the resolver SHALL treat it as a session alias and apply the following steps before proceeding with Section 6.1:¶

1. Normalize the alias: percent-decode, then fold to lowercase.¶
2. Look up the normalized alias in the alias registry for the agent identified by agent-name.¶
3. If a matching entry is found, substitute the corresponding session identifier into the resolution process and continue with Section 6.1 step 2.¶
4. If no matching entry is found, the URI is unresolvable (Section 6.3). Implementations SHOULD report "alias not registered" as a distinct unresolvable condition, separate from "session log not found."¶

6.3. Unresolvable URIs

A prompt URI is unresolvable if any of the following conditions hold:¶

• The URI is in remote form (prompt://) and the host subcomponent does not match the hostname of the machine on which the resolver is running (case-insensitive comparison). A resolver MUST NOT attempt to forward the request to another machine; it SHALL return an error indicating the host mismatch.¶
• The URI is in remote form and contains a username subcomponent that does not match the OS-level username of the user under whose account the resolver is operating (case-insensitive comparison). The resolver SHALL return an error indicating the user mismatch.¶
• The session-ref is a session alias that is not registered in the alias registry.¶
• The session log for the resolved session identifier is not accessible to the resolver.¶
• The session log has been deleted, expired, or is otherwise unavailable.¶
• The agent-name is not recognized by the resolver.¶
• No session log entries fall within the resolution window.¶

An unresolvable URI is NOT invalid. The URI remains a valid provenance identifier and SHALL be preserved in provenance records even when the referenced session is no longer accessible. Resolvers SHOULD distinguish between "unresolvable" and "invalid" when reporting resolution status, and SHOULD report host-mismatch and user-mismatch conditions as distinct errors to aid debugging.¶

When resolution succeeds, the resolver SHALL return the canonical URI in the same form as the URI that was presented for resolution: if the input was a local-only URI (prompt:/...), the returned canonical_uri SHALL be in local form; if the input was a remote URI (prompt://...), the returned canonical_uri SHALL be in remote form, preserving the host, username (if present), and port (if non-default) from the input URI.¶

8.1. Mitigation

Implementations SHOULD use millisecond-precision timestamps (rather than second-precision) to reduce the probability of within-session collisions. With millisecond precision, a collision requires two distinct prompts to arrive within the same millisecond, which is negligible in interactive use.¶

Implementations MAY append a fragment identifier to a prompt URI to encode an agent-internal correlation identifier when that identifier is known at call time:¶

prompt:/claude-code/5674b542.../2026-07-07T16:45:23.856Z#id=abc123

Fragment identifiers used for this purpose are implementation-specific and are OPTIONAL and not required for interoperability. Resolvers that do not recognize a fragment identifier SHOULD ignore it and apply the standard resolution algorithm.¶

8.2. Disclosure Requirement

Implementations that generate prompt URIs SHOULD document the timestamp precision they use and the conditions under which within-session collisions are possible, so that consumers of provenance records can assess the reliability of URI-based prompt identification in their deployment context.¶

Operation

Git invokes prepare-commit-msg after the initial commit message is prepared but before the editor is opened. The hook:¶

1. Examines the draft commit message for a Co-authored-by: Copilot trailer injected automatically by VS Code / GitHub Copilot.¶
2. If the trailer is present and no Prompt-URL: trailer already exists, queries the local prompt-url-mcp daemon (via its find_prompt tool, Section 9) for the most recent Copilot prompt submitted within the past 30 minutes.¶
3. If a result is returned, appends a Prompt-URL: trailer containing the local-form prompt URI (prompt:/github-copilot/...) to the commit message.¶
4. If the daemon is not running or returns no results, exits silently without modifying the commit message. The hook MUST NOT block a commit under any error condition.¶

Installation

The hook is a Node.js script that requires Node.js in PATH and the prompt-url-mcp daemon to be running. It is located at hooks/prepare-commit-msg in the reference implementation repository.¶

Per-repository installation:¶

cp hooks/prepare-commit-msg .git/hooks/prepare-commit-msg
chmod +x .git/hooks/prepare-commit-msg

Global installation (applies to all repositories for the current user). The recommended global hooks directory is ~/.git-hooks/:¶

git config --global core.hooksPath ~/.git-hooks
mkdir -p ~/.git-hooks
cp hooks/prepare-commit-msg ~/.git-hooks/prepare-commit-msg
chmod +x ~/.git-hooks/prepare-commit-msg

On Windows the chmod command may be run in Git Bash or WSL. Git for Windows treats copied scripts as executable by default.¶

Resulting Commit Message

A commit message with Copilot co-authorship, after the hook appends the trailer, takes the following form:¶

feat: add user registration validation

Implement unique-email check at registration time. Returns 409
if the email address is already in use.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Prompt-URL: prompt:/github-copilot/95602ecf-.../~8e16a698-...