taskseam 0.1.1__tar.gz → 0.2.1__tar.gz

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 (32) hide show
  1. {taskseam-0.1.1 → taskseam-0.2.1}/PKG-INFO +57 -13
  2. {taskseam-0.1.1 → taskseam-0.2.1}/README.md +56 -12
  3. {taskseam-0.1.1 → taskseam-0.2.1}/pyproject.toml +1 -1
  4. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam/__init__.py +1 -1
  5. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam/__main__.py +146 -17
  6. taskseam-0.2.1/taskseam/demo.py +94 -0
  7. taskseam-0.2.1/taskseam/doctor.py +177 -0
  8. taskseam-0.2.1/taskseam/hooks.py +145 -0
  9. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam/mcp.py +90 -14
  10. taskseam-0.2.1/taskseam/render.py +78 -0
  11. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam/setup.py +46 -7
  12. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam/store.py +93 -7
  13. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam.egg-info/PKG-INFO +57 -13
  14. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam.egg-info/SOURCES.txt +6 -0
  15. {taskseam-0.1.1 → taskseam-0.2.1}/tests/test_cli.py +4 -0
  16. taskseam-0.2.1/tests/test_continuity_features.py +248 -0
  17. taskseam-0.2.1/tests/test_doctor.py +117 -0
  18. {taskseam-0.1.1 → taskseam-0.2.1}/tests/test_mcp.py +8 -0
  19. {taskseam-0.1.1 → taskseam-0.2.1}/tests/test_setup.py +38 -5
  20. {taskseam-0.1.1 → taskseam-0.2.1}/tests/test_store.py +37 -1
  21. {taskseam-0.1.1 → taskseam-0.2.1}/LICENSE +0 -0
  22. {taskseam-0.1.1 → taskseam-0.2.1}/setup.cfg +0 -0
  23. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam/api.py +0 -0
  24. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam/importer.py +0 -0
  25. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam/workspace.py +0 -0
  26. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam.egg-info/dependency_links.txt +0 -0
  27. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam.egg-info/entry_points.txt +0 -0
  28. {taskseam-0.1.1 → taskseam-0.2.1}/taskseam.egg-info/top_level.txt +0 -0
  29. {taskseam-0.1.1 → taskseam-0.2.1}/tests/test_api.py +0 -0
  30. {taskseam-0.1.1 → taskseam-0.2.1}/tests/test_end_to_end.py +0 -0
  31. {taskseam-0.1.1 → taskseam-0.2.1}/tests/test_importer.py +0 -0
  32. {taskseam-0.1.1 → taskseam-0.2.1}/tests/test_workspace.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: taskseam
3
- Version: 0.1.1
3
+ Version: 0.2.1
4
4
  Summary: Local-first task continuity across AI coding agents
5
5
  Author: Sai Sandeep Kantareddy
6
6
  Maintainer: Sai Sandeep Kantareddy
@@ -27,25 +27,55 @@ Description-Content-Type: text/markdown
27
27
  License-File: LICENSE
28
28
  Dynamic: license-file
29
29
 
30
- # TaskSeam
30
+ # 🧵 TaskSeam
31
31
 
32
- **Switch AI. Keep working.**
32
+ ## **Switch AI. Keep working.**
33
33
 
34
- TaskSeam keeps the accepted state of a project available when work moves between Codex, Claude Code, VS Code agents, ChatGPT, and Claude.
34
+ *Local-first task continuity across independent AI coding agents.*
35
35
 
36
- [Website](https://taskseam.github.io/taskseam/) · [Editor setup](https://github.com/TaskSeam/taskseam/blob/main/docs/EDITOR_SETUP.md) · [Quick start](https://github.com/TaskSeam/taskseam/blob/main/docs/QUICKSTART.md) · [Demo](https://github.com/TaskSeam/taskseam/blob/main/docs/DEMO.md) · [Privacy](https://github.com/TaskSeam/taskseam/blob/main/PRIVACY.md)
36
+ TaskSeam carries accepted decisions, active constraints, and unresolved questions between Codex, Claude Code, and VS Code agents. Each project stays local, and each connected agent receives only the changes it has not seen.
37
+
38
+ [Website](https://taskseam.github.io/taskseam/) · [Why TaskSeam](https://github.com/TaskSeam/taskseam/blob/main/docs/WHY_TASKSEAM.md) · [Editor setup](https://github.com/TaskSeam/taskseam/blob/main/docs/EDITOR_SETUP.md) · [Demo](https://github.com/TaskSeam/taskseam/blob/main/docs/DEMO.md) · [Privacy](https://github.com/TaskSeam/taskseam/blob/main/PRIVACY.md)
39
+
40
+ ```mermaid
41
+ flowchart LR
42
+ A["Claude Code<br/>Accept a decision"] --> T["TaskSeam<br/>Current project state"]
43
+ T --> B["Codex<br/>Continue with the decision"]
44
+ B --> C["Codex<br/>Add a constraint"]
45
+ C --> T
46
+ T --> D["Claude Code<br/>Receive only what changed"]
47
+ ```
48
+
49
+ **Local SQLite · Open source · MCP compatible · No hosted account**
37
50
 
38
51
  > **Public alpha:** The local CLI, MCP server, agent plugin, project state, provenance, and per-agent continuation are working. The browser extension is a developer preview.
39
52
 
53
+ ## The problem: context rot
54
+
55
+ Switching AI tools often means reconstructing the task instead of continuing it:
56
+
57
+ 1. Re-explain the project and its current direction.
58
+ 2. Paste long chat histories that consume the next agent's context window.
59
+ 3. Correct suggestions that conflict with decisions or constraints established elsewhere.
60
+
61
+ TaskSeam stores the current task state under the project's `.taskseam/` directory. It shares concise, source-linked state through MCP instead of copying entire conversations between tools.
62
+
40
63
  ## Quick start
41
64
 
42
- Install TaskSeam:
65
+ Install TaskSeam as an isolated command-line application, then watch it work in a throwaway project:
43
66
 
44
67
  ```bash
45
68
  pipx install taskseam
69
+ taskseam demo # one minute, no agents or settings touched
70
+ ```
71
+
72
+ Standard pip installation also works:
73
+
74
+ ```bash
75
+ python3 -m pip install taskseam
46
76
  ```
47
77
 
48
- Connect the supported agents installed on your computer:
78
+ Connect the supported agents installed on your computer. Their CLIs or VS Code/Cursor extensions are detected automatically:
49
79
 
50
80
  ```bash
51
81
  taskseam setup
@@ -64,7 +94,21 @@ Start with this prompt:
64
94
 
65
95
  > Continue this project. What accepted decisions, constraints, and open questions should I know?
66
96
 
67
- There are no routine TaskSeam commands after initialization.
97
+ There are no routine TaskSeam commands after initialization. In Claude Code and Codex, `taskseam setup` installs a session-start hook, so each new chat starts with the project's state even before you ask. Codex asks you to trust the hook once in `/hooks`.
98
+
99
+ ## Everyday commands
100
+
101
+ You rarely need these, because agents record state through their approval screen. They are useful when you want to check or correct that state yourself:
102
+
103
+ ```bash
104
+ taskseam doctor # is everything connected? prints the fix if not
105
+ taskseam show # what every agent will see, in plain text
106
+ taskseam drop 3f9a --reason "Offline mode cut" # retire an item that no longer applies
107
+ taskseam export --agents-md # mirror state into AGENTS.md for non-MCP agents
108
+ taskseam export --history # deterministic JSON, including superseded items
109
+ ```
110
+
111
+ Item IDs accept any unique prefix of four or more characters.
68
112
 
69
113
  ## What changes for the user?
70
114
 
@@ -126,11 +170,11 @@ The [five-minute demo](https://github.com/TaskSeam/taskseam/blob/main/docs/DEMO.
126
170
 
127
171
  The [public roadmap](https://github.com/TaskSeam/taskseam/blob/main/ROADMAP.md) tracks the current priorities:
128
172
 
129
- 1. Validate clean installation across supported operating systems.
130
- 2. Publish the Python package to PyPI.
131
- 3. Package and submit the browser extension.
132
- 4. Improve automatic task matching and correction.
133
- 5. Publish repeatable continuity evaluations.
173
+ 1. Retry-safe delivery: acknowledge exactly what an agent received.
174
+ 2. Publish repeatable continuity evaluations.
175
+ 3. Validate clean installation across supported operating systems.
176
+ 4. Package and submit the browser extension.
177
+ 5. Improve automatic task matching and correction.
134
178
 
135
179
  ## Development
136
180
 
@@ -1,22 +1,52 @@
1
- # TaskSeam
1
+ # 🧵 TaskSeam
2
2
 
3
- **Switch AI. Keep working.**
3
+ ## **Switch AI. Keep working.**
4
4
 
5
- TaskSeam keeps the accepted state of a project available when work moves between Codex, Claude Code, VS Code agents, ChatGPT, and Claude.
5
+ *Local-first task continuity across independent AI coding agents.*
6
6
 
7
- [Website](https://taskseam.github.io/taskseam/) · [Editor setup](https://github.com/TaskSeam/taskseam/blob/main/docs/EDITOR_SETUP.md) · [Quick start](https://github.com/TaskSeam/taskseam/blob/main/docs/QUICKSTART.md) · [Demo](https://github.com/TaskSeam/taskseam/blob/main/docs/DEMO.md) · [Privacy](https://github.com/TaskSeam/taskseam/blob/main/PRIVACY.md)
7
+ TaskSeam carries accepted decisions, active constraints, and unresolved questions between Codex, Claude Code, and VS Code agents. Each project stays local, and each connected agent receives only the changes it has not seen.
8
+
9
+ [Website](https://taskseam.github.io/taskseam/) · [Why TaskSeam](https://github.com/TaskSeam/taskseam/blob/main/docs/WHY_TASKSEAM.md) · [Editor setup](https://github.com/TaskSeam/taskseam/blob/main/docs/EDITOR_SETUP.md) · [Demo](https://github.com/TaskSeam/taskseam/blob/main/docs/DEMO.md) · [Privacy](https://github.com/TaskSeam/taskseam/blob/main/PRIVACY.md)
10
+
11
+ ```mermaid
12
+ flowchart LR
13
+ A["Claude Code<br/>Accept a decision"] --> T["TaskSeam<br/>Current project state"]
14
+ T --> B["Codex<br/>Continue with the decision"]
15
+ B --> C["Codex<br/>Add a constraint"]
16
+ C --> T
17
+ T --> D["Claude Code<br/>Receive only what changed"]
18
+ ```
19
+
20
+ **Local SQLite · Open source · MCP compatible · No hosted account**
8
21
 
9
22
  > **Public alpha:** The local CLI, MCP server, agent plugin, project state, provenance, and per-agent continuation are working. The browser extension is a developer preview.
10
23
 
24
+ ## The problem: context rot
25
+
26
+ Switching AI tools often means reconstructing the task instead of continuing it:
27
+
28
+ 1. Re-explain the project and its current direction.
29
+ 2. Paste long chat histories that consume the next agent's context window.
30
+ 3. Correct suggestions that conflict with decisions or constraints established elsewhere.
31
+
32
+ TaskSeam stores the current task state under the project's `.taskseam/` directory. It shares concise, source-linked state through MCP instead of copying entire conversations between tools.
33
+
11
34
  ## Quick start
12
35
 
13
- Install TaskSeam:
36
+ Install TaskSeam as an isolated command-line application, then watch it work in a throwaway project:
14
37
 
15
38
  ```bash
16
39
  pipx install taskseam
40
+ taskseam demo # one minute, no agents or settings touched
41
+ ```
42
+
43
+ Standard pip installation also works:
44
+
45
+ ```bash
46
+ python3 -m pip install taskseam
17
47
  ```
18
48
 
19
- Connect the supported agents installed on your computer:
49
+ Connect the supported agents installed on your computer. Their CLIs or VS Code/Cursor extensions are detected automatically:
20
50
 
21
51
  ```bash
22
52
  taskseam setup
@@ -35,7 +65,21 @@ Start with this prompt:
35
65
 
36
66
  > Continue this project. What accepted decisions, constraints, and open questions should I know?
37
67
 
38
- There are no routine TaskSeam commands after initialization.
68
+ There are no routine TaskSeam commands after initialization. In Claude Code and Codex, `taskseam setup` installs a session-start hook, so each new chat starts with the project's state even before you ask. Codex asks you to trust the hook once in `/hooks`.
69
+
70
+ ## Everyday commands
71
+
72
+ You rarely need these, because agents record state through their approval screen. They are useful when you want to check or correct that state yourself:
73
+
74
+ ```bash
75
+ taskseam doctor # is everything connected? prints the fix if not
76
+ taskseam show # what every agent will see, in plain text
77
+ taskseam drop 3f9a --reason "Offline mode cut" # retire an item that no longer applies
78
+ taskseam export --agents-md # mirror state into AGENTS.md for non-MCP agents
79
+ taskseam export --history # deterministic JSON, including superseded items
80
+ ```
81
+
82
+ Item IDs accept any unique prefix of four or more characters.
39
83
 
40
84
  ## What changes for the user?
41
85
 
@@ -97,11 +141,11 @@ The [five-minute demo](https://github.com/TaskSeam/taskseam/blob/main/docs/DEMO.
97
141
 
98
142
  The [public roadmap](https://github.com/TaskSeam/taskseam/blob/main/ROADMAP.md) tracks the current priorities:
99
143
 
100
- 1. Validate clean installation across supported operating systems.
101
- 2. Publish the Python package to PyPI.
102
- 3. Package and submit the browser extension.
103
- 4. Improve automatic task matching and correction.
104
- 5. Publish repeatable continuity evaluations.
144
+ 1. Retry-safe delivery: acknowledge exactly what an agent received.
145
+ 2. Publish repeatable continuity evaluations.
146
+ 3. Validate clean installation across supported operating systems.
147
+ 4. Package and submit the browser extension.
148
+ 5. Improve automatic task matching and correction.
105
149
 
106
150
  ## Development
107
151
 
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "taskseam"
7
- version = "0.1.1"
7
+ version = "0.2.1"
8
8
  description = "Local-first task continuity across AI coding agents"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.9"
@@ -1,3 +1,3 @@
1
1
  """Local task state and handoff tools."""
2
2
 
3
- __version__ = "0.1.1"
3
+ __version__ = "0.2.1"
@@ -68,6 +68,8 @@ def parser():
68
68
  setup.add_argument("tool", nargs="?", choices=("codex", "claude-code"),
69
69
  help="Configure one tool; omit to configure every detected tool")
70
70
  setup.add_argument("--dry-run", action="store_true")
71
+ setup.add_argument("--no-hooks", action="store_true",
72
+ help="Skip the session-start hook that loads project state automatically")
71
73
  commands.add_parser("prompt", help="Print the prompt for creating an import packet")
72
74
  import_command = commands.add_parser("import", help="Preview or apply a TaskSeam state packet")
73
75
  import_command.add_argument("path", nargs="?", help="JSON file; omit to read standard input")
@@ -84,12 +86,89 @@ def parser():
84
86
  handoff = commands.add_parser("handoff", help="Deliver changes since a target's last handoff")
85
87
  handoff.add_argument("--to", required=True, dest="target")
86
88
  handoff.add_argument("--task-id", help="Defaults to the active workspace task")
89
+ handoff.add_argument("--full", action="store_true",
90
+ help="Also include current state for a fresh chat or lost context")
91
+ show = commands.add_parser("show", help="Print the active task's state in readable form")
92
+ show.add_argument("task_id", nargs="?", help="Defaults to the active workspace task")
93
+ drop = commands.add_parser("drop", help="Retire an item that no longer applies")
94
+ drop.add_argument("item_id", help="Item ID or unique prefix")
95
+ drop.add_argument("--reason", required=True)
96
+ drop.add_argument("--source", default="manual")
97
+ export = commands.add_parser("export", help="Write deterministic JSON or Markdown state")
98
+ export.add_argument("--format", choices=("json", "markdown"), default="json")
99
+ export.add_argument("--history", action="store_true",
100
+ help="Include superseded, resolved, and retired items (JSON only)")
101
+ destination = export.add_mutually_exclusive_group()
102
+ destination.add_argument("--output", "-o", help="Write to a file instead of standard output")
103
+ destination.add_argument("--agents-md", nargs="?", const="AGENTS.md", metavar="PATH",
104
+ help="Maintain a TaskSeam block inside AGENTS.md (or PATH)")
105
+ export.add_argument("--task-id", help="Defaults to the active workspace task")
106
+ demo = commands.add_parser("demo", help="One-minute walkthrough in a temporary project")
107
+ demo.add_argument("--pause", type=float, default=None, help="Seconds between steps")
108
+ doctor = commands.add_parser("doctor", help="Check agent connections and this project's state")
109
+ doctor.add_argument("--json", action="store_true", help="Print machine-readable results")
110
+ doctor.add_argument("--skip-mcp", action="store_true",
111
+ help="Do not ask agent CLIs whether the MCP server is registered")
112
+ hook = commands.add_parser("hook", help="Agent session hooks")
113
+ hook_sub = hook.add_subparsers(dest="action", required=True)
114
+ hook_sub.add_parser("session-start", help="Print state for a SessionStart hook (reads hook JSON)")
115
+ hook_install = hook_sub.add_parser("install", help="Install the SessionStart hook")
116
+ hook_install.add_argument("tool", nargs="?", choices=("codex", "claude-code"))
117
+ hook_install.add_argument("--dry-run", action="store_true")
87
118
  return p
88
119
 
89
120
 
121
+ def _task_or_active(task_id, workspace):
122
+ task_id = task_id or (active_task(workspace) if workspace else None)
123
+ if not task_id:
124
+ raise ValueError("Provide a task ID or run this command in a TaskSeam workspace")
125
+ return task_id
126
+
127
+
128
+ def _print_setup_summary(result, dry_run, tool=None):
129
+ names = {"claude-code": "Claude Code", "codex": "Codex"}
130
+ connected = [{"tool": tool, **result}] if tool else result.get("configured", [])
131
+ lines = []
132
+ for entry in connected:
133
+ if entry.get("tool"):
134
+ how = entry.get("found_via", "")
135
+ lines.append(" {} {}{}".format("would connect" if dry_run else "connected", names[entry["tool"]],
136
+ " (" + how + ")" if how and how != "PATH" else ""))
137
+ for entry in result.get("skipped", []):
138
+ lines.append(" skipped {}: {}".format(names.get(entry["tool"], entry["tool"]), entry["reason"]))
139
+ for entry in (result.get("session_hooks") or {}).get("hooks", []):
140
+ if entry["tool"] == "codex" and entry["status"] != "unchanged":
141
+ lines.append(" Codex: open /hooks once and trust the TaskSeam hook")
142
+ if lines:
143
+ print("\nTaskSeam setup" + (" (dry run, nothing written)" if dry_run else "") + ":\n" +
144
+ "\n".join(lines) + "\nNext: cd your-project && taskseam init, then `taskseam doctor`.",
145
+ file=sys.stderr)
146
+
147
+
148
+ def _agents_md_block(task, items):
149
+ from .render import brief
150
+ body = brief(task, items, header=False)
151
+ body = "\n".join("#" + line if line.startswith("## ") else line for line in body.splitlines())
152
+ return "## Project state (TaskSeam: {})\n\n{}\n".format(task["title"], body)
153
+
154
+
90
155
  def main(argv=None):
91
156
  args = parser().parse_args(argv)
92
157
  try:
158
+ if args.command == "demo":
159
+ from .demo import run as run_demo
160
+ return run_demo(args.pause)
161
+ if args.command == "doctor":
162
+ from .doctor import diagnose, render
163
+ sections = diagnose(probe_mcp=not args.skip_mcp)
164
+ if args.json:
165
+ print(json.dumps([{"section": title, "checks": checks} for title, checks in sections],
166
+ indent=2))
167
+ return 1 if any(c["status"] == "fail" for _, cs in sections for c in cs) else 0
168
+ return render(sections)
169
+ if args.command == "hook" and args.action == "session-start":
170
+ from .hooks import session_start
171
+ return session_start()
93
172
  if args.command == "init":
94
173
  title = args.title or Path.cwd().name
95
174
 
@@ -103,6 +182,9 @@ def main(argv=None):
103
182
  root, config = initialize(Path.cwd(), title, create_task)
104
183
  print(json.dumps({"workspace": str(root), "project": config["project"],
105
184
  "active_task": config["active_task"]}, indent=2))
185
+ print("\nTaskSeam is ready in {}.\nNext: open this folder in Claude Code or Codex and "
186
+ "start a new chat.\nCheck the connection any time with: taskseam doctor".format(root),
187
+ file=sys.stderr)
106
188
  return 0
107
189
  if args.command == "prompt":
108
190
  from .importer import PACKET_PROMPT
@@ -129,7 +211,12 @@ def main(argv=None):
129
211
  result = setup_claude(sys.executable, args.dry_run)
130
212
  else:
131
213
  result = setup_detected(sys.executable, args.dry_run)
214
+ if not args.no_hooks:
215
+ from .hooks import install_detected
216
+ tools = {"codex": ["codex"], "claude-code": ["claude-code"]}.get(args.tool)
217
+ result["session_hooks"] = install_detected(sys.executable, args.dry_run, tools)
132
218
  print(json.dumps(result, indent=2))
219
+ _print_setup_summary(result, args.dry_run, args.tool)
133
220
  return 0
134
221
  if args.command == "import":
135
222
  from .importer import parse_packet
@@ -164,6 +251,11 @@ def main(argv=None):
164
251
  from .mcp import run
165
252
  run(args.db, task_id=active_task(workspace) if workspace else None)
166
253
  return 0
254
+ if args.command == "hook":
255
+ from .hooks import install_detected
256
+ tools = [args.tool] if args.tool else None
257
+ print(json.dumps(install_detected(sys.executable, args.dry_run, tools), indent=2))
258
+ return 0
167
259
  if args.command == "version":
168
260
  from . import __version__
169
261
  print(__version__)
@@ -180,29 +272,66 @@ def main(argv=None):
180
272
  elif args.command == "event":
181
273
  result = {"event_id": store.add_event(args.task_id, args.source, args.body)}
182
274
  elif args.command == "item":
275
+ supersedes = args.supersedes and store.resolve_item_id(args.supersedes, args.task_id)
183
276
  result = {"item_id": store.add_item(args.task_id, args.kind, args.body,
184
- args.source, args.supersedes)}
185
- elif args.command == "record":
186
- if not workspace:
187
- raise ValueError("No TaskSeam workspace found; run 'taskseam init'")
188
- result = {"item_id": store.add_item(active_task(workspace), args.kind, args.body,
189
- args.source, args.supersedes)}
190
- elif args.command == "resolve":
277
+ args.source, supersedes)}
278
+ elif args.command in ("record", "resolve", "supersede", "drop"):
191
279
  if not workspace:
192
280
  raise ValueError("No TaskSeam workspace found; run 'taskseam init'")
193
- result = {"item_id": store.resolve_question(active_task(workspace), args.question_id,
194
- args.decision, args.source, args.supersedes),
195
- "resolved_question": args.question_id}
196
- elif args.command == "supersede":
197
- if not workspace:
198
- raise ValueError("No TaskSeam workspace found; run 'taskseam init'")
199
- store.set_supersession(active_task(workspace), args.old_item_id, args.new_item_id)
200
- result = {"superseded": args.old_item_id, "replacement": args.new_item_id}
281
+ task_id = active_task(workspace)
282
+
283
+ def ref(value):
284
+ return store.resolve_item_id(value, task_id) if value else None
285
+
286
+ if args.command == "record":
287
+ result = {"item_id": store.add_item(task_id, args.kind, args.body,
288
+ args.source, ref(args.supersedes))}
289
+ elif args.command == "resolve":
290
+ question_id = ref(args.question_id)
291
+ result = {"item_id": store.resolve_question(task_id, question_id, args.decision,
292
+ args.source, ref(args.supersedes)),
293
+ "resolved_question": question_id}
294
+ elif args.command == "supersede":
295
+ old, new = ref(args.old_item_id), ref(args.new_item_id)
296
+ store.set_supersession(task_id, old, new)
297
+ result = {"superseded": old, "replacement": new}
298
+ else:
299
+ result = store.retire_item(task_id, ref(args.item_id), args.reason, args.source)
300
+ elif args.command == "show":
301
+ from .render import brief
302
+ context = store.context(_task_or_active(args.task_id, workspace))
303
+ print(brief(context["task"], context["items"]), end="")
304
+ return 0
305
+ elif args.command == "export":
306
+ from .render import brief, splice_agents_md
307
+ task_id = _task_or_active(args.task_id, workspace)
308
+ if args.history and args.format != "json":
309
+ raise ValueError("--history is only available with --format json")
310
+ if args.agents_md:
311
+ context = store.context(task_id)
312
+ target = Path(args.agents_md)
313
+ existing = target.read_text(encoding="utf-8") if target.exists() else ""
314
+ target.write_text(splice_agents_md(
315
+ existing, _agents_md_block(context["task"], context["items"])), encoding="utf-8")
316
+ print("taskseam: updated {}. It is usually committed to Git; review the block "
317
+ "before sharing.".format(target), file=sys.stderr)
318
+ return 0
319
+ if args.format == "json":
320
+ text = json.dumps(store.export(task_id, history=args.history), indent=2,
321
+ sort_keys=True) + "\n"
322
+ else:
323
+ snapshot = store.export(task_id)
324
+ text = brief(snapshot["task"], snapshot["items"])
325
+ if args.output:
326
+ Path(args.output).write_text(text, encoding="utf-8")
327
+ else:
328
+ sys.stdout.write(text)
329
+ return 0
201
330
  elif args.command == "handoff":
202
331
  task_id = args.task_id or (active_task(workspace) if workspace else None)
203
332
  if not task_id:
204
333
  raise ValueError("Provide a task ID or run this command in a TaskSeam workspace")
205
- result = store.handoff(task_id, args.target)
334
+ result = store.handoff(task_id, args.target, full=args.full)
206
335
  elif args.command == "checkpoint":
207
336
  task_id = args.task_id or (active_task(workspace) if workspace else None)
208
337
  if not task_id:
@@ -216,7 +345,7 @@ def main(argv=None):
216
345
  raise ValueError("Provide a task ID or run this command in a TaskSeam workspace")
217
346
  result = store.context(task_id)
218
347
  else:
219
- result = store.explain(args.item_id)
348
+ result = store.explain(store.resolve_item_id(args.item_id))
220
349
  print(json.dumps(result, indent=2))
221
350
  return 0
222
351
  finally:
@@ -0,0 +1,94 @@
1
+ """`taskseam demo`: a one-minute, agent-free walkthrough in a temporary project."""
2
+
3
+ import json
4
+ import sys
5
+ import tempfile
6
+ import time
7
+ from pathlib import Path
8
+
9
+ from .hooks import session_start
10
+ from .render import brief, short
11
+ from .store import Store
12
+ from .workspace import database_path, find_workspace, initialize
13
+
14
+
15
+ def run(pause=None, stream=None):
16
+ stream = stream or sys.stdout
17
+ color = hasattr(stream, "isatty") and stream.isatty()
18
+ if pause is None:
19
+ pause = 1.2 if color else 0.0
20
+
21
+ def say(text):
22
+ stream.write("\n" + ("\033[1m# " + text + "\033[0m" if color else "# " + text) + "\n")
23
+ stream.flush()
24
+ time.sleep(pause)
25
+
26
+ def show(text):
27
+ stream.write(text if text.endswith("\n") else text + "\n")
28
+ stream.flush()
29
+
30
+ with tempfile.TemporaryDirectory(prefix="taskseam-demo-") as directory:
31
+ root = Path(directory)
32
+
33
+ def create(path, title):
34
+ store = Store(path)
35
+ try:
36
+ return store.create_task(title)
37
+ finally:
38
+ store.close()
39
+
40
+ initialize(root, "Invoice exporter", create)
41
+ workspace = find_workspace(root)
42
+ task = workspace[1]["active_task"]
43
+ store = Store(database_path(workspace))
44
+ try:
45
+ say("Monday, in Claude Code: you accept a decision, and the agent saves it")
46
+ pdf = store.add_item(task, "decision", "Export invoices as PDF", "claude-code")
47
+ store.add_item(task, "constraint", "Never send invoice data to third-party services", "user")
48
+ store.add_item(task, "question", "Should exports include voided invoices?", "claude-code")
49
+ store.handoff(task, "claude-code")
50
+ context = store.context(task)
51
+ show(brief(context["task"], context["items"], header=False, ids=False))
52
+
53
+ say("Tuesday, in Codex: you change your mind. CSV replaces PDF, plus a new rule")
54
+ csv = store.add_item(task, "decision", "Export invoices as CSV, not PDF", "codex", pdf)
55
+ store.add_item(task, "constraint", "CSV must follow RFC 4180", "codex")
56
+ show("saved. The PDF decision is superseded, not deleted")
57
+
58
+ say("Any new chat, in any agent: the session-start hook loads current state")
59
+ show("(no prompting, no pasted history. The old PDF decision is gone)")
60
+ stdin = _Input(json.dumps({"cwd": str(root), "source": "startup"}))
61
+ session_start(stdin, stream)
62
+
63
+ say("Back in Claude Code: it receives only what changed since its last visit")
64
+ delta = store.handoff(task, "claude-code")
65
+ for item in delta["added"]:
66
+ show(" + {}: {}".format(item["kind"], item["body"]))
67
+ for item in delta["removed"]:
68
+ show(" - {}: {}".format(item["kind"], item["body"]))
69
+
70
+ say("Every item keeps its evidence")
71
+ evidence = store.explain(csv)
72
+ show(" {} `{}` <- {} at {}".format(evidence["body"], short(csv), evidence["source"],
73
+ evidence["event_time"][:16].replace("T", " ")))
74
+ finally:
75
+ store.close()
76
+
77
+ say("Try it in your own project")
78
+ show(" taskseam setup # connect Claude Code and Codex (CLI or editor extension)\n"
79
+ " cd your-project && taskseam init\n"
80
+ " taskseam doctor # confirm everything is connected")
81
+ return 0
82
+
83
+
84
+ class _Input:
85
+ """Minimal stdin stand-in for the hook (not a TTY)."""
86
+
87
+ def __init__(self, text):
88
+ self.text = text
89
+
90
+ def isatty(self):
91
+ return False
92
+
93
+ def read(self):
94
+ return self.text