trissue 0.0.0-stage → 0.1.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.
Files changed (4) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +146 -2
  3. package/dist/cli.js +2680 -0
  4. package/package.json +31 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pxl
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,147 @@
1
- # Temporary Holding Version
1
+ # trissue
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
+ Have the coding agent already on your computer find the source of an issue and
4
+ write it up, then file it, copy it, or send it wherever the project wants.
5
+
6
+ ```sh
7
+ bunx trissue MileniumHQ/Paperboard
8
+ ```
9
+
10
+ 1. trissue downloads the repo and warns you before anything else: an agent is
11
+ about to read it, so you should trust it.
12
+ 2. You explain the issue.
13
+ 3. You pick an agent and a model. Only agents installed on your computer are
14
+ listed.
15
+ 4. The agent investigates the repo, read-only, and writes the issue. You can
16
+ steer it while it works, or press `esc` to stop.
17
+ 5. You file the issue on GitHub, copy it, or open one of the project's links.
18
+
19
+ ## Agents
20
+
21
+ trissue talks to agents over the [Agent Client Protocol](https://agentclientprotocol.com).
22
+ It runs the agents you have installed and never downloads one.
23
+
24
+ | Agent | Detected by | Runs |
25
+ |---|---|---|
26
+ | Claude Code | `claude` | `claude -p`, driven directly over its stream-json protocol |
27
+ | Codex | `codex` | the bundled Codex ACP adapter, with your `codex` |
28
+ | Cursor | `cursor-agent` | `cursor-agent acp` |
29
+ | Grok | `grok` | `grok agent stdio` |
30
+ | OpenCode | `opencode` | `opencode acp` |
31
+ | Antigravity | `agy_acp_server.par` | `agy_acp_server.par` |
32
+ | Everything else in the ACP registry | its program | its ACP command |
33
+
34
+ Claude Code has no native ACP, and its ACP adapter needs Anthropic's
35
+ proprietary SDK plus a second copy of Claude Code, so trissue drives your
36
+ `claude` directly instead. The Codex ACP adapter (Apache-2.0) ships inside
37
+ trissue-embedded as one file, unmodified, with its notices. The registry list
38
+ is a snapshot in `packages/embedded/src/registry.json`; `bun run
39
+ update-registry` refreshes it.
40
+
41
+ ### What the agent can do
42
+
43
+ The agent may read and search the repo. Claude Code only gets its Read, Grep
44
+ and Glob tools: no shell, no MCP servers, and none of the repo's own `.claude`
45
+ settings (so a repo can't add hooks). ACP agents get every permission request
46
+ to edit, delete, move, run, or fetch refused, and start in their read-only
47
+ mode when they have one (Codex does). The prompt also says the repo's instructions are
48
+ untrusted: the agent checks them first and rejects the task if they ask for
49
+ anything beyond writing the issue.
50
+
51
+ ## Configuring a repo
52
+
53
+ Put a `.trissue.json` at the repo root. Every field is optional.
54
+
55
+ ```json
56
+ {
57
+ "$schema": "https://unpkg.com/trissue-embedded/trissue.schema.json",
58
+ "product": { "name": "Paperboard", "color": "#8AB4FF" },
59
+ "background": "#000000",
60
+ "prompt": "Explain the issue you're experiencing",
61
+ "instructions": "How issues for this project should be written…",
62
+ "models": { "allow": ["claude/*", "codex/*"], "block": ["*haiku*"] },
63
+ "checkmark": "green",
64
+ "github": "MileniumHQ/Paperboard",
65
+ "labels": ["triage"],
66
+ "links": [
67
+ { "label": "Discord", "url": "https://discord.gg/example", "description": "Opens the #bugs channel." },
68
+ { "label": "Email", "url": "mailto:bugs@example.com?subject={title}&body={body}" }
69
+ ]
70
+ }
71
+ ```
72
+
73
+ - `instructions` replaces the default issue-writing guide (adapted from
74
+ [t3dotgg/tstack](https://github.com/t3dotgg/tstack)). It only shapes how the
75
+ issue is written; the agent is told to reject anything else.
76
+ - `models` patterns match `agent/model` (`claude/opus`) or, without a slash,
77
+ the model id alone. `allow` narrows, `block` removes.
78
+ - `github` defaults to the repo itself when it's on github.com. `false` hides
79
+ GitHub filing.
80
+ - `links` open in the browser or mail app. `{title}`, `{body}` and `{issue}`
81
+ become the URL-encoded issue.
82
+
83
+ Brand colors of agents can't be configured.
84
+
85
+ ## Without the interface
86
+
87
+ Everything can be passed as arguments:
88
+
89
+ ```sh
90
+ trissue MileniumHQ/Paperboard --issue "The server panel says Stopped after a restart" \
91
+ --agent claude --model opus --send github --yes
92
+ ```
93
+
94
+ `--send` is `print` (default), `json`, `copy`, `github` (needs `--yes`), or
95
+ `link:<label>`. `--issue -` reads the issue from stdin. `trissue --list-agents`
96
+ lists what's installed.
97
+
98
+ ## In an app
99
+
100
+ The engine is its own package, without the terminal interface:
101
+
102
+ ```sh
103
+ npm install trissue-embedded
104
+ ```
105
+
106
+ ```ts
107
+ import { runTriage, detectHarnesses, fileGitHubIssue } from "trissue-embedded";
108
+
109
+ const agents = detectHarnesses(); // for your own picker
110
+ const { issue, source } = await runTriage({
111
+ repo: "MileniumHQ/Paperboard",
112
+ issue: "The server panel says Stopped after a restart",
113
+ harness: agents[0]?.id,
114
+ onEvent: (event) => render(event), // thinking, messages, tool calls
115
+ });
116
+ await fileGitHubIssue("MileniumHQ/Paperboard", issue);
117
+ await source.dispose();
118
+ ```
119
+
120
+ For a step-by-step UI (pick a model after the agent starts, steer, stop), use
121
+ `startAgent` and the `AgentSession` it returns; `Transcript` turns its events
122
+ into rows. trissue-embedded runs on Node 20+, Bun and Electron.
123
+
124
+ ## Packages
125
+
126
+ | Package | What it is |
127
+ |---|---|
128
+ | [`trissue`](packages/cli) | The command and its terminal interface. Needs Bun 1.3.14 or newer. |
129
+ | [`trissue-embedded`](packages/embedded) | The engine: agents, config, prompts, sending. No interface. |
130
+
131
+ ## Development
132
+
133
+ ```sh
134
+ bun install
135
+ bun start <repo> # builds the engine, then runs the interface from source
136
+ bun run build # builds both packages
137
+ bun run screenshots # renders every screen to screenshots/
138
+ bun run typecheck
139
+ ```
140
+
141
+ The interface is built with [OpenTUI](https://github.com/anomalyco/opentui)
142
+ and Solid.
143
+
144
+ ## License
145
+
146
+ MIT. The bundled Codex adapter is Apache-2.0; see
147
+ `dist/adapters/THIRD_PARTY_NOTICES.md` in trissue-embedded.