teamtrail 0.0.1 → 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/LICENSE CHANGED
@@ -6,7 +6,7 @@ FSL-1.1-ALv2
6
6
 
7
7
  ## Notice
8
8
 
9
- Copyright 2026 TeamTrail
9
+ Copyright 2026 Teamtrail
10
10
 
11
11
  ## Terms and Conditions
12
12
 
package/README.md CHANGED
@@ -1,13 +1,105 @@
1
- # TeamTrail
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
- **A local command center for big work done by your AI coding agents.** You pick the destination, your agents map the work as decisions, and you get only the calls that need you.
3
+ # teamtrail
4
4
 
5
- ## Status
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
- **Not released yet.** This package is a placeholder until launch; running it only prints a short message.
7
+ **[teamtrail.app](https://teamtrail.app)** · [Docs](https://teamtrail.app/docs/) · [GitHub](https://github.com/teamtrailhq/teamtrail)
8
8
 
9
- Watch the repository: **[github.com/teamtrailhq/teamtrail](https://github.com/teamtrailhq/teamtrail)**.
9
+ ```bash
10
+ npm i -g teamtrail # or skip the install: npx teamtrail
11
+ cd your-repo
12
+ teamtrail
13
+ ```
10
14
 
11
- ## License
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.
12
16
 
13
- [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.
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 |
23
+
24
+ Requires Node 20 or newer. No other runtime dependencies.
25
+
26
+ ## Connect your coding agent
27
+
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
31
+
32
+ ```bash
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
65
+ ```
66
+
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.
104
+
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
+ ```