teamtrail 0.0.2 → 0.7.0-next.14
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.
- package/README.md +90 -15
- package/THIRD_PARTY_NOTICES.md +29 -0
- package/dist/app/assets/figtree-latin-ext-wght-normal-DCwSJGxG.woff2 +0 -0
- package/dist/app/assets/figtree-latin-wght-normal-D_ZTVpCC.woff2 +0 -0
- package/dist/app/assets/index-BDDk3We0.js +146 -0
- package/dist/app/assets/index-DNIvhx9x.css +1 -0
- package/dist/app/assets/jetbrains-mono-cyrillic-wght-normal-D73BlboJ.woff2 +0 -0
- package/dist/app/assets/jetbrains-mono-greek-wght-normal-Bw9x6K1M.woff2 +0 -0
- package/dist/app/assets/jetbrains-mono-latin-ext-wght-normal-DBQx-q_a.woff2 +0 -0
- package/dist/app/assets/jetbrains-mono-latin-wght-normal-B9CIFXIH.woff2 +0 -0
- package/dist/app/assets/jetbrains-mono-vietnamese-wght-normal-Bt-aOZkq.woff2 +0 -0
- package/dist/app/assets/londrina-solid-latin-400-normal-B9GE5EkC.woff2 +0 -0
- package/dist/app/assets/londrina-solid-latin-400-normal-BH8LiSvY.woff +0 -0
- package/dist/app/assets/londrina-solid-latin-900-normal-DRvOezkF.woff +0 -0
- package/dist/app/assets/londrina-solid-latin-900-normal-KrKknq8v.woff2 +0 -0
- package/dist/app/index.html +17 -0
- package/dist/cli.js +58331 -0
- package/package.json +23 -5
- package/index.js +0 -8
package/README.md
CHANGED
|
@@ -1,30 +1,105 @@
|
|
|
1
1
|
<img src="https://raw.githubusercontent.com/teamtrailhq/teamtrail/main/brand/teamtrail-banner.gif" alt="Scout, the voice of Teamtrail, next to the Teamtrail logo and a trail through the mountains." width="100%" />
|
|
2
2
|
|
|
3
|
-
#
|
|
3
|
+
# teamtrail
|
|
4
4
|
|
|
5
|
-
**The trail map for your AI coding agents.** You pick the destination, your agents walk the trail, and you only get the calls that need you.
|
|
5
|
+
**The trail map for your AI coding agents.** You pick the destination, your agents walk the trail, and you only get the calls that need you. One command opens it for the agents working in your repo.
|
|
6
6
|
|
|
7
7
|
**[teamtrail.app](https://teamtrail.app)** · [Docs](https://teamtrail.app/docs/) · [GitHub](https://github.com/teamtrailhq/teamtrail)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
```bash
|
|
10
|
+
npm i -g teamtrail # or skip the install: npx teamtrail
|
|
11
|
+
cd your-repo
|
|
12
|
+
teamtrail
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`teamtrail` starts a local server, opens the Lookout in your browser and keeps trails as markdown in `./.teamtrail/` in the current folder. Commit that folder or ignore it; agents and people can edit the files directly, and changes show up live.
|
|
10
16
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
17
|
+
| Option | Default | |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| `--dir <path>` | `./.teamtrail` (or `$TEAMTRAIL_DIR`) | Tracker folder |
|
|
20
|
+
| `--port <n>` | `7420`, next free port if taken | Port |
|
|
21
|
+
| `--host <addr>` | `127.0.0.1` | Interface to bind. The server can write files in the tracker folder, so only expose it on networks you trust. |
|
|
22
|
+
| `--no-open` | | Don't open the browser |
|
|
16
23
|
|
|
17
|
-
|
|
24
|
+
Requires Node 20 or newer. No other runtime dependencies.
|
|
18
25
|
|
|
19
|
-
##
|
|
26
|
+
## Connect your coding agent
|
|
20
27
|
|
|
21
|
-
The
|
|
28
|
+
The same package ships an MCP server, `teamtrail mcp`, that your agent starts over stdio. Nothing else to install. Run `teamtrail` in the repo as well to watch the agent live and answer its questions in the Lookout.
|
|
29
|
+
|
|
30
|
+
### Claude Code
|
|
22
31
|
|
|
23
32
|
```bash
|
|
24
|
-
|
|
25
|
-
|
|
33
|
+
claude mcp add teamtrail -- npx -y teamtrail mcp
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Or let `teamtrail` do it and add the `/scout` command to the repo (`.claude/commands/scout.md`):
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npx teamtrail connect claude
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Then, in Claude Code:
|
|
43
|
+
|
|
44
|
+
| Command | Does |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| `/scout new "<idea>"` | Frames the idea with you, then charts a trail |
|
|
47
|
+
| `/scout resume [trail]` | Picks up the trail and works ready tickets |
|
|
48
|
+
| `/scout status` | Progress, running sessions, what's waiting and blocked, spend |
|
|
49
|
+
| `/scout inbox` | Questions waiting on you; answer them in the chat |
|
|
50
|
+
|
|
51
|
+
### Codex
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
codex mcp add teamtrail -- npx -y teamtrail mcp
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
or in `~/.codex/config.toml`:
|
|
58
|
+
|
|
59
|
+
```toml
|
|
60
|
+
[mcp_servers.teamtrail]
|
|
61
|
+
command = "npx"
|
|
62
|
+
args = ["-y", "teamtrail", "mcp"]
|
|
63
|
+
# ask_human waits for your answer; Codex cancels tool calls after 60 s by default.
|
|
64
|
+
tool_timeout_sec = 900
|
|
26
65
|
```
|
|
27
66
|
|
|
28
|
-
|
|
67
|
+
`npx teamtrail connect codex` prints this and installs the same command as a Codex prompt (`~/.codex/prompts/scout.md`): `/prompts:scout new "<idea>"`, `/prompts:scout resume`, and so on.
|
|
68
|
+
|
|
69
|
+
### Other agents
|
|
70
|
+
|
|
71
|
+
Any MCP client works: run `npx -y teamtrail mcp` over stdio in the repo. `--dir <path>` (or `$TEAMTRAIL_DIR`) picks another tracker folder; `--agent <trail name>` fixes the session name, which otherwise comes from the client (`claude-01`, `codex-01`).
|
|
72
|
+
|
|
73
|
+
### Tools
|
|
74
|
+
|
|
75
|
+
| Tool | |
|
|
76
|
+
| --- | --- |
|
|
77
|
+
| `status` | Trails, progress, ready / claimed / blocked tickets, sessions, waiting questions, decisions, spend |
|
|
78
|
+
| `start_trail` | Create a trail: destination, notes, decided, not yet specified, out of scope, tickets with blocking edges |
|
|
79
|
+
| `resume_trail` | Open a session on a trail; returns status, your claim and the next ready ticket |
|
|
80
|
+
| `update_trail` | Edit destination or notes, add Not yet specified / Out of scope lines, switch mode |
|
|
81
|
+
| `next_ticket` | The next ready ticket with its blockers' decisions (does not claim) |
|
|
82
|
+
| `claim_ticket` / `release_ticket` | Assign a ticket to the agent (next ready by default) / give it back |
|
|
83
|
+
| `add_ticket` | Add a ticket or promote a Not yet specified line |
|
|
84
|
+
| `report_progress` | Step, log line, chat message; tokens and cost only when no agent log is read (see Usage) |
|
|
85
|
+
| `close_ticket` | Resolve (or rule out) a ticket: resolution comment, close, DecisionRecord, unblocked tickets |
|
|
86
|
+
| `record_decision` | Keep any other decision as a DecisionRecord |
|
|
87
|
+
| `ask_human` / `wait_for_answer` | Ask the human through the Lookout inbox and wait for the answer |
|
|
88
|
+
| `list_inbox` / `answer_question` | Questions from every agent; answer one with the human's words from the chat |
|
|
89
|
+
|
|
90
|
+
Sessions, questions and usage reach the Lookout through `.teamtrail/.agents/`, so the agent and the Lookout can start in any order.
|
|
91
|
+
|
|
92
|
+
### Claims are leases
|
|
93
|
+
|
|
94
|
+
A claim lasts 15 minutes and every tool call from the claiming agent renews it (so do waits on `ask_human`). If the agent crashes or goes silent, the lease expires and the ticket goes back to the queue: the Lookout checks every 15 s, and so does any agent calling `next_ticket` or `claim_ticket`. The ticket gets a **Returned to queue** comment with the agent's `report_progress` notes and decisions, and the next agent's `claim_ticket` returns it as `resume`. The return is an ordinary tracker write (comment + unassign), so on GitHub and Linear it goes through the offline outbox like any other write. Tickets close to expiry show as **Stalled** in the Lookout, which can also release them by hand. Set the length with `--lease-minutes <n>` or `$TEAMTRAIL_LEASE_MINUTES`.
|
|
95
|
+
|
|
96
|
+
### Usage
|
|
97
|
+
|
|
98
|
+
Tokens and cost per session are measured from the agent's own local logs, priced at list rates, and tagged `LOG` in the sessions area:
|
|
99
|
+
|
|
100
|
+
- **Claude Code:** the session transcript (`~/.claude/projects/<project>/<session>.jsonl`). `connect claude` also adds a silent `SessionStart` hook to `.claude/settings.local.json` that records which transcript belongs to the repo.
|
|
101
|
+
- **Codex:** the session rollout (`~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`), found from the tool call's thread id. Nothing to install.
|
|
102
|
+
|
|
103
|
+
Other agents report usage through `report_progress`; those numbers are tagged `SELF`. Nothing leaves your machine.
|
|
29
104
|
|
|
30
|
-
|
|
105
|
+
Concepts derived from mattpocock/skills (MIT); see `THIRD_PARTY_NOTICES.md`.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Third-party notices
|
|
2
|
+
|
|
3
|
+
## mattpocock/skills
|
|
4
|
+
|
|
5
|
+
Derived from mattpocock/skills (MIT) — https://github.com/mattpocock/skills. The trail model (destination, frontier, "Not yet specified" list, decisions, out of scope), the junction / prototype / research ticket types and the HITL / AFK split adapt the concepts of its `docs/engineering/wayfinder.md` workflow.
|
|
6
|
+
|
|
7
|
+
```
|
|
8
|
+
MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2026 Matt Pocock
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
25
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
26
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
27
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
28
|
+
SOFTWARE.
|
|
29
|
+
```
|
|
Binary file
|
|
Binary file
|