@tangenta/claude-code 0.0.0-stage → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,15 @@
1
+ {
2
+ "name": "tangenta",
3
+ "version": "0.19.0",
4
+ "description": "Attaches Claude Code to a Tangenta issue: the issue page shows the session's plan and activity, and people on it can message, answer and stop Claude.",
5
+ "author": { "name": "Tangenta" },
6
+ "keywords": ["tangenta", "issues", "agents"],
7
+ "userConfig": {
8
+ "api_url": {
9
+ "type": "string",
10
+ "title": "Tangenta API address",
11
+ "description": "Only for a self-hosted Tangenta: its API address. Leave it empty for the hosted Tangenta. TANGENTA_API_URL in the environment wins over it.",
12
+ "required": false
13
+ }
14
+ }
15
+ }
package/.mcp.json ADDED
@@ -0,0 +1,10 @@
1
+ {
2
+ "mcpServers": {
3
+ "session": {
4
+ "type": "stdio",
5
+ "command": "node",
6
+ "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/mcp-proxy.mjs"],
7
+ "env": { "TANGENTA_PLUGIN_API_URL": "${user_config.api_url}" }
8
+ }
9
+ }
10
+ }
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Koode
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,28 @@
1
- # Temporary Holding Version
1
+ # @tangenta/claude-code
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The [Tangenta](https://tangenta.app) plugin for Claude Code. It attaches your own Claude Code to
4
+ a Tangenta issue: the issue page shows the session's plan and activity, and the people you
5
+ choose can message Claude, answer its questions and stop it. Hooks deliver what happens on the
6
+ issue to Claude; a local MCP server forwards the session tools to Tangenta with the session's
7
+ token. Plain JavaScript for Node 20 or later, no dependencies.
8
+
9
+ It needs a Tangenta instance: the hosted one at tangenta.app, or your own.
10
+
11
+ ## Install
12
+
13
+ Every Tangenta instance serves a marketplace file that pins this package to the version the
14
+ instance runs:
15
+
16
+ ```sh
17
+ claude plugin marketplace add https://tangenta.app/integrations/claude-code/marketplace.json
18
+ claude plugin install tangenta@tangenta
19
+ ```
20
+
21
+ For a self-hosted instance, use that instance's address in the first command and set the
22
+ plugin's `api_url` option to its API address (or `TANGENTA_API_URL` in the shell you start
23
+ Claude Code from). The hosted Tangenta needs no setting.
24
+
25
+ Then open an issue in Tangenta, start an agent session and send the prompt it gives you to
26
+ Claude Code. See `docs/AGENTS.md` in the Tangenta repository for the trust rules and the limits.
27
+
28
+ MIT licensed.
@@ -0,0 +1,67 @@
1
+ {
2
+ "description": "Tangenta session hooks: attach from the prompt, deliver messages from Tangenta, stop on request and end the session.",
3
+ "hooks": {
4
+ "UserPromptSubmit": [
5
+ {
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "node",
10
+ "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs"],
11
+ "timeout": 20
12
+ }
13
+ ]
14
+ }
15
+ ],
16
+ "PreToolUse": [
17
+ {
18
+ "matcher": "*",
19
+ "hooks": [
20
+ {
21
+ "type": "command",
22
+ "command": "node",
23
+ "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs"],
24
+ "timeout": 15
25
+ }
26
+ ]
27
+ }
28
+ ],
29
+ "PostToolUse": [
30
+ {
31
+ "matcher": "*",
32
+ "hooks": [
33
+ {
34
+ "type": "command",
35
+ "command": "node",
36
+ "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs"],
37
+ "timeout": 15
38
+ }
39
+ ]
40
+ }
41
+ ],
42
+ "Stop": [
43
+ {
44
+ "hooks": [
45
+ {
46
+ "type": "command",
47
+ "command": "node",
48
+ "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs"],
49
+ "timeout": 600
50
+ }
51
+ ]
52
+ }
53
+ ],
54
+ "SessionEnd": [
55
+ {
56
+ "hooks": [
57
+ {
58
+ "type": "command",
59
+ "command": "node",
60
+ "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs"],
61
+ "timeout": 2
62
+ }
63
+ ]
64
+ }
65
+ ]
66
+ }
67
+ }
package/lib/config.mjs ADDED
@@ -0,0 +1,200 @@
1
+ /**
2
+ * Settings of the Tangenta plugin, read from the environment Claude Code gives hooks and the
3
+ * MCP proxy. Every switch of the plugin lives here, so a change of default is one edit.
4
+ *
5
+ * Environment:
6
+ * TANGENTA_API_URL the Tangenta API's address; wins over the plugin option and
7
+ * the attach line's address (without any, the hosted Tangenta)
8
+ * CLAUDE_PLUGIN_OPTION_API_URL the plugin option `api_url`, as Claude Code exports it to hooks
9
+ * TANGENTA_PLUGIN_API_URL the same option, as the plugin's MCP server receives it
10
+ * TANGENTA_ALLOW_HTTP 1 allows plain http to another machine
11
+ * TANGENTA_PLUGIN_STATE_DIR where attached sessions are kept, instead of the plugin's data
12
+ * directory (tests and the spike use a throwaway one)
13
+ * TANGENTA_POLL_INTERVAL_MS the least time between two input checks after tool calls
14
+ * TANGENTA_QUESTION_WAIT_SECONDS how long the Stop hook waits for the answer to a question
15
+ * TANGENTA_EMIT_ACTIONS 0 turns off reporting each tool call as an action
16
+ */
17
+ import { homedir } from "node:os";
18
+ import { join, resolve } from "node:path";
19
+
20
+ /** The least time between two input checks after tool calls, unless the environment says. */
21
+ export const DEFAULT_POLL_INTERVAL_MS = 5_000;
22
+
23
+ /**
24
+ * How long the Stop hook waits for the answer to an open question before it lets the turn
25
+ * end. The hook's own timeout in hooks.json must stay above it.
26
+ */
27
+ export const DEFAULT_QUESTION_WAIT_SECONDS = 300;
28
+
29
+ /** Upper bound for TANGENTA_QUESTION_WAIT_SECONDS, below the Stop hook's 600-second timeout. */
30
+ export const MAX_QUESTION_WAIT_SECONDS = 540;
31
+
32
+ /** How often the Stop hook checks for the answer while it waits. */
33
+ export const QUESTION_POLL_MS = 3_000;
34
+
35
+ /** Time limit of one request to Tangenta from a hook that runs before or after a tool call. */
36
+ export const REQUEST_TIMEOUT_MS = 5_000;
37
+
38
+ /**
39
+ * Time limit of the end-of-session request. Claude Code gives all plugin SessionEnd hooks
40
+ * 1.5 seconds together, and a plugin's own timeout can't raise that.
41
+ */
42
+ export const SESSION_END_TIMEOUT_MS = 1_200;
43
+
44
+ /**
45
+ * Whether the attach prompt still reaches Claude after the plugin takes its token. True: the
46
+ * prompt goes through, so the issue's prompt starts the work at once, and the token is in
47
+ * Claude's context (the PreToolUse guard denies any tool call that carries it). False: the
48
+ * plugin blocks the prompt, the token never reaches Claude, and the user sends the work
49
+ * prompt as a second message.
50
+ */
51
+ export const ATTACH_PROMPT_REACHES_CLAUDE = true;
52
+
53
+ /**
54
+ * The attach prompt's first line: `<product> session <ISSUE-ID> (<api url>): tng_ses_<secret>`,
55
+ * where ` (<api url>)` is optional (older instances leave it out). The product name follows the
56
+ * instance's branding, so any name before "session" is accepted; the session token's form is
57
+ * what identifies the line. Groups: issue, API address or undefined, token.
58
+ */
59
+ export const ATTACH_LINE =
60
+ /^[^\s:][^:\r\n]{0,59} session ([A-Z][A-Z0-9_]*-\d+)(?: \((https?:\/\/[^\s()]+)\))?: (tng_ses_[A-Za-z0-9_-]{43})\s*$/;
61
+
62
+ /** A session token anywhere in a text, as in a `start_session` answer. */
63
+ export const TOKEN_PATTERN = /tng_ses_[A-Za-z0-9_-]{43}/g;
64
+
65
+ /** The session tools the plugin's MCP server offers; hooks never check inputs around them. */
66
+ export const SESSION_TOOLS = ["get_session", "emit_activity", "update_plan", "ask", "end_session"];
67
+
68
+ /** The name of the plugin's MCP server in `.mcp.json`. */
69
+ export const PROXY_SERVER = "session";
70
+
71
+ /** Whether `name` is a tool of the plugin's own MCP server. */
72
+ export function isSessionTool(name) {
73
+ const match = /^mcp__(.+)__([a-z_]+)$/.exec(name ?? "");
74
+ if (!match) return false;
75
+ const [, server, tool] = match;
76
+ const ours = server === PROXY_SERVER || server.endsWith(`_${PROXY_SERVER}`);
77
+ return ours && SESSION_TOOLS.includes(tool);
78
+ }
79
+
80
+ /** Whether `name` is `start_session` on some other MCP server (the user's own Tangenta). */
81
+ export function isStartSessionTool(name) {
82
+ return /^mcp__.+__start_session$/.test(name ?? "") && !isSessionTool(name);
83
+ }
84
+
85
+ export class ConfigError extends Error {}
86
+
87
+ /** `localhost`, `127.0.0.0/8` or `::1`. */
88
+ function isLoopback(hostname) {
89
+ return hostname === "localhost" || hostname === "[::1]" || /^127(\.\d{1,3}){3}$/.test(hostname);
90
+ }
91
+
92
+ /** A value Claude Code left unsubstituted, such as `${user_config.api_url}` when unset. */
93
+ function present(value) {
94
+ return typeof value === "string" && value.trim() !== "" && !value.includes("${");
95
+ }
96
+
97
+ /**
98
+ * `raw` as an API address without a trailing slash, as a URL. Refuses plain http to another
99
+ * machine unless TANGENTA_ALLOW_HTTP=1, since the session token travels with every request.
100
+ */
101
+ function checkedAddress(raw, env) {
102
+ let url;
103
+ try {
104
+ url = new URL(raw.trim());
105
+ } catch {
106
+ throw new ConfigError(`The Tangenta API address ${raw} isn't a valid URL.`);
107
+ }
108
+ const httpAllowed = isLoopback(url.hostname) || env.TANGENTA_ALLOW_HTTP === "1";
109
+ if (url.protocol !== "https:" && !(url.protocol === "http:" && httpAllowed)) {
110
+ throw new ConfigError(
111
+ `The Tangenta API address ${raw} isn't https, so the session token could be read ` +
112
+ "on the way. Use https, or set TANGENTA_ALLOW_HTTP=1.",
113
+ );
114
+ }
115
+ return url;
116
+ }
117
+
118
+ /** The configured address (environment or plugin option), checked; null when there is none. */
119
+ function configuredAddress(env) {
120
+ const raw = [
121
+ env.TANGENTA_API_URL,
122
+ env.CLAUDE_PLUGIN_OPTION_API_URL,
123
+ env.TANGENTA_PLUGIN_API_URL,
124
+ ].find(present);
125
+ return raw ? checkedAddress(raw, env) : null;
126
+ }
127
+
128
+ /**
129
+ * The hosted Tangenta's API address, used when nothing names another one. The product's
130
+ * brand identity (`packages/brand`) does not hold it yet, and this plugin has no
131
+ * dependencies, so it lives here.
132
+ */
133
+ export const HOSTED_API_URL = "https://api.tangenta.app";
134
+
135
+ /**
136
+ * The Tangenta API's address without a trailing slash: TANGENTA_API_URL, else the plugin
137
+ * option `api_url`, else the hosted Tangenta.
138
+ */
139
+ export function apiUrl(env) {
140
+ const url = configuredAddress(env) ?? new URL(HOSTED_API_URL);
141
+ return url.href.replace(/\/+$/, "");
142
+ }
143
+
144
+ /**
145
+ * The address a session attaches to, where the token and the session's activity go: a
146
+ * configured address wins, and an attach line that names another origin than it is refused;
147
+ * else the line's own address (under the same https rule), else the hosted Tangenta. The
148
+ * built-in default never conflicts with a line, so a line that names a self-hosted instance
149
+ * attaches to it. `lineUrl` is only ever the address from the user's own prompt.
150
+ */
151
+ export function attachApiUrl(env, lineUrl) {
152
+ if (!lineUrl) return apiUrl(env);
153
+ const named = checkedAddress(lineUrl, env);
154
+ const configured = configuredAddress(env);
155
+ if (configured && configured.origin !== named.origin) {
156
+ throw new ConfigError(
157
+ `This prompt is for the Tangenta at ${named.origin}, but the plugin is set to ` +
158
+ `${configured.origin}. Nothing was attached and no token was sent. Change api_url ` +
159
+ "(or TANGENTA_API_URL) if that Tangenta is the one you mean.",
160
+ );
161
+ }
162
+ return (configured ?? named).href.replace(/\/+$/, "");
163
+ }
164
+
165
+ /** The directory that holds attached sessions, outside every project. */
166
+ export function stateRoot(env) {
167
+ if (present(env.TANGENTA_PLUGIN_STATE_DIR)) return resolve(env.TANGENTA_PLUGIN_STATE_DIR);
168
+ if (present(env.CLAUDE_PLUGIN_DATA)) return resolve(env.CLAUDE_PLUGIN_DATA);
169
+ const config = present(env.XDG_CONFIG_HOME) ? env.XDG_CONFIG_HOME : join(homedir(), ".config");
170
+ return resolve(config, "tangenta", "claude-code");
171
+ }
172
+
173
+ /** The project directory Claude Code runs in. */
174
+ export function projectDir(env, hookInput) {
175
+ if (present(env.CLAUDE_PROJECT_DIR)) return resolve(env.CLAUDE_PROJECT_DIR);
176
+ if (present(hookInput?.cwd)) return resolve(hookInput.cwd);
177
+ return resolve(process.cwd());
178
+ }
179
+
180
+ function integer(value, fallback, { min, max }) {
181
+ const parsed = Number.parseInt(value ?? "", 10);
182
+ if (Number.isNaN(parsed)) return fallback;
183
+ return Math.min(Math.max(parsed, min), max);
184
+ }
185
+
186
+ export function pollIntervalMs(env) {
187
+ return integer(env.TANGENTA_POLL_INTERVAL_MS, DEFAULT_POLL_INTERVAL_MS, { min: 0, max: 600_000 });
188
+ }
189
+
190
+ export function questionWaitMs(env) {
191
+ const seconds = integer(env.TANGENTA_QUESTION_WAIT_SECONDS, DEFAULT_QUESTION_WAIT_SECONDS, {
192
+ min: 0,
193
+ max: MAX_QUESTION_WAIT_SECONDS,
194
+ });
195
+ return seconds * 1000;
196
+ }
197
+
198
+ export function emitActions(env) {
199
+ return env.TANGENTA_EMIT_ACTIONS !== "0";
200
+ }