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 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
- # Teamtrail
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
- Teamtrail is a local trail map for big work done by AI coding agents. You describe a trail, your agents chart it as decision tickets, and they claim the work over MCP while you steer from the Lookout, a web app on your machine.
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
- - **Trails and decision tickets:** a live map of what's decided, in progress, blocked and out of scope.
12
- - **Waiting on you:** every question from every agent in one inbox, ranked by what matters.
13
- - **Scout:** briefs you when you come back and only calls you for the turns that are yours to make.
14
- - **Verified outcomes:** acceptance criteria tied to evidence, so "done" means proven.
15
- - **Local-first:** trails are plain markdown in `./.teamtrail/` in your repo, or in your GitHub Issues or Linear. Nothing needs a Teamtrail server.
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
- Works with any coding agent that connects over MCP. Claude Code and Codex are the primary supported agents.
24
+ Requires Node 20 or newer. No other runtime dependencies.
18
25
 
19
- ## Try it
26
+ ## Connect your coding agent
20
27
 
21
- The public release isn't out yet, so this package is a placeholder. The preview is on the `next` tag:
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
- cd your-repo
25
- npx teamtrail@next
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
- ## License
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
- [FSL-1.1-ALv2](LICENSE): free to use, modify and run, including at work, for anything except a competing product. Each release becomes Apache 2.0 two years after it ships.
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
+ ```