taskseam 0.2.0__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.2.0 → taskseam-0.2.1}/PKG-INFO +5 -3
  2. {taskseam-0.2.0 → taskseam-0.2.1}/README.md +4 -2
  3. {taskseam-0.2.0 → taskseam-0.2.1}/pyproject.toml +1 -1
  4. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/__init__.py +1 -1
  5. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/__main__.py +41 -0
  6. taskseam-0.2.1/taskseam/demo.py +94 -0
  7. taskseam-0.2.1/taskseam/doctor.py +177 -0
  8. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/hooks.py +3 -3
  9. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/setup.py +46 -7
  10. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam.egg-info/PKG-INFO +5 -3
  11. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam.egg-info/SOURCES.txt +3 -0
  12. taskseam-0.2.1/tests/test_doctor.py +117 -0
  13. {taskseam-0.2.0 → taskseam-0.2.1}/tests/test_setup.py +38 -5
  14. {taskseam-0.2.0 → taskseam-0.2.1}/LICENSE +0 -0
  15. {taskseam-0.2.0 → taskseam-0.2.1}/setup.cfg +0 -0
  16. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/api.py +0 -0
  17. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/importer.py +0 -0
  18. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/mcp.py +0 -0
  19. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/render.py +0 -0
  20. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/store.py +0 -0
  21. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam/workspace.py +0 -0
  22. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam.egg-info/dependency_links.txt +0 -0
  23. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam.egg-info/entry_points.txt +0 -0
  24. {taskseam-0.2.0 → taskseam-0.2.1}/taskseam.egg-info/top_level.txt +0 -0
  25. {taskseam-0.2.0 → taskseam-0.2.1}/tests/test_api.py +0 -0
  26. {taskseam-0.2.0 → taskseam-0.2.1}/tests/test_cli.py +0 -0
  27. {taskseam-0.2.0 → taskseam-0.2.1}/tests/test_continuity_features.py +0 -0
  28. {taskseam-0.2.0 → taskseam-0.2.1}/tests/test_end_to_end.py +0 -0
  29. {taskseam-0.2.0 → taskseam-0.2.1}/tests/test_importer.py +0 -0
  30. {taskseam-0.2.0 → taskseam-0.2.1}/tests/test_mcp.py +0 -0
  31. {taskseam-0.2.0 → taskseam-0.2.1}/tests/test_store.py +0 -0
  32. {taskseam-0.2.0 → 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.2.0
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
@@ -62,10 +62,11 @@ TaskSeam stores the current task state under the project's `.taskseam/` director
62
62
 
63
63
  ## Quick start
64
64
 
65
- Install TaskSeam as an isolated command-line application:
65
+ Install TaskSeam as an isolated command-line application, then watch it work in a throwaway project:
66
66
 
67
67
  ```bash
68
68
  pipx install taskseam
69
+ taskseam demo # one minute, no agents or settings touched
69
70
  ```
70
71
 
71
72
  Standard pip installation also works:
@@ -74,7 +75,7 @@ Standard pip installation also works:
74
75
  python3 -m pip install taskseam
75
76
  ```
76
77
 
77
- 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:
78
79
 
79
80
  ```bash
80
81
  taskseam setup
@@ -100,6 +101,7 @@ There are no routine TaskSeam commands after initialization. In Claude Code and
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:
101
102
 
102
103
  ```bash
104
+ taskseam doctor # is everything connected? prints the fix if not
103
105
  taskseam show # what every agent will see, in plain text
104
106
  taskseam drop 3f9a --reason "Offline mode cut" # retire an item that no longer applies
105
107
  taskseam export --agents-md # mirror state into AGENTS.md for non-MCP agents
@@ -33,10 +33,11 @@ TaskSeam stores the current task state under the project's `.taskseam/` director
33
33
 
34
34
  ## Quick start
35
35
 
36
- Install TaskSeam as an isolated command-line application:
36
+ Install TaskSeam as an isolated command-line application, then watch it work in a throwaway project:
37
37
 
38
38
  ```bash
39
39
  pipx install taskseam
40
+ taskseam demo # one minute, no agents or settings touched
40
41
  ```
41
42
 
42
43
  Standard pip installation also works:
@@ -45,7 +46,7 @@ Standard pip installation also works:
45
46
  python3 -m pip install taskseam
46
47
  ```
47
48
 
48
- 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:
49
50
 
50
51
  ```bash
51
52
  taskseam setup
@@ -71,6 +72,7 @@ There are no routine TaskSeam commands after initialization. In Claude Code and
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:
72
73
 
73
74
  ```bash
75
+ taskseam doctor # is everything connected? prints the fix if not
74
76
  taskseam show # what every agent will see, in plain text
75
77
  taskseam drop 3f9a --reason "Offline mode cut" # retire an item that no longer applies
76
78
  taskseam export --agents-md # mirror state into AGENTS.md for non-MCP agents
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "taskseam"
7
- version = "0.2.0"
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.2.0"
3
+ __version__ = "0.2.1"
@@ -103,6 +103,12 @@ def parser():
103
103
  destination.add_argument("--agents-md", nargs="?", const="AGENTS.md", metavar="PATH",
104
104
  help="Maintain a TaskSeam block inside AGENTS.md (or PATH)")
105
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")
106
112
  hook = commands.add_parser("hook", help="Agent session hooks")
107
113
  hook_sub = hook.add_subparsers(dest="action", required=True)
108
114
  hook_sub.add_parser("session-start", help="Print state for a SessionStart hook (reads hook JSON)")
@@ -119,6 +125,26 @@ def _task_or_active(task_id, workspace):
119
125
  return task_id
120
126
 
121
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
+
122
148
  def _agents_md_block(task, items):
123
149
  from .render import brief
124
150
  body = brief(task, items, header=False)
@@ -129,6 +155,17 @@ def _agents_md_block(task, items):
129
155
  def main(argv=None):
130
156
  args = parser().parse_args(argv)
131
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)
132
169
  if args.command == "hook" and args.action == "session-start":
133
170
  from .hooks import session_start
134
171
  return session_start()
@@ -145,6 +182,9 @@ def main(argv=None):
145
182
  root, config = initialize(Path.cwd(), title, create_task)
146
183
  print(json.dumps({"workspace": str(root), "project": config["project"],
147
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)
148
188
  return 0
149
189
  if args.command == "prompt":
150
190
  from .importer import PACKET_PROMPT
@@ -176,6 +216,7 @@ def main(argv=None):
176
216
  tools = {"codex": ["codex"], "claude-code": ["claude-code"]}.get(args.tool)
177
217
  result["session_hooks"] = install_detected(sys.executable, args.dry_run, tools)
178
218
  print(json.dumps(result, indent=2))
219
+ _print_setup_summary(result, args.dry_run, args.tool)
179
220
  return 0
180
221
  if args.command == "import":
181
222
  from .importer import parse_packet
@@ -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
@@ -0,0 +1,177 @@
1
+ """`taskseam doctor`: explain exactly what is connected and how to fix what is not."""
2
+
3
+ import json
4
+ import shlex
5
+ import subprocess
6
+ import sys
7
+ from pathlib import Path
8
+
9
+ from . import __version__
10
+ from .hooks import HOOK_MARKER, claude_settings_path, codex_hooks_path
11
+ from .setup import find_agent
12
+ from .store import SCHEMA_VERSION, Store
13
+ from .workspace import active_task, database_path, find_workspace
14
+
15
+ AGENTS = (("Claude Code", "claude-code", "claude", claude_settings_path),
16
+ ("Codex", "codex", "codex", codex_hooks_path))
17
+
18
+
19
+ def _check(status, name, detail, fix=None):
20
+ return {"status": status, "check": name, "detail": detail, "fix": fix}
21
+
22
+
23
+ def _mcp_registration(executable, tool):
24
+ try:
25
+ result = subprocess.run([executable, "mcp", "get", "taskseam"], capture_output=True,
26
+ text=True, timeout=30)
27
+ except (OSError, subprocess.TimeoutExpired) as exc:
28
+ return _check("warn", "MCP server", "could not ask {}: {}".format(tool, exc))
29
+ if result.returncode != 0:
30
+ return _check("fail", "MCP server", "taskseam is not registered",
31
+ "taskseam setup " + tool)
32
+ output = result.stdout + result.stderr
33
+ if "taskseam" in output and sys.executable not in output and "-m taskseam" in output:
34
+ return _check("warn", "MCP server",
35
+ "registered with a different Python than this TaskSeam ({})".format(sys.executable),
36
+ "taskseam setup " + tool)
37
+ return _check("ok", "MCP server", "registered")
38
+
39
+
40
+ def _hook(path, tool):
41
+ if not path.exists():
42
+ return _check("fail", "Session-start hook", "not installed ({} missing)".format(path),
43
+ "taskseam hook install " + tool)
44
+ try:
45
+ data = json.loads(path.read_text(encoding="utf-8") or "{}")
46
+ except (OSError, ValueError) as exc:
47
+ return _check("fail", "Session-start hook", "cannot read {}: {}".format(path, exc))
48
+ groups = ((data.get("hooks") or {}).get("SessionStart") or []) if isinstance(data, dict) else []
49
+ for group in groups:
50
+ for handler in (group.get("hooks") or []) if isinstance(group, dict) else []:
51
+ command = str(handler.get("command", "")) if isinstance(handler, dict) else ""
52
+ if HOOK_MARKER not in command:
53
+ continue
54
+ try:
55
+ python = shlex.split(command)[0]
56
+ except (ValueError, IndexError):
57
+ python = ""
58
+ if python and not Path(python).exists():
59
+ return _check("fail", "Session-start hook",
60
+ "points to a Python that no longer exists: " + python,
61
+ "taskseam hook install " + tool)
62
+ detail = "installed in " + str(path)
63
+ if tool == "codex":
64
+ detail += "; Codex runs it after you trust it once in /hooks"
65
+ return _check("ok", "Session-start hook", detail)
66
+ return _check("fail", "Session-start hook", "not installed in " + str(path),
67
+ "taskseam hook install " + tool)
68
+
69
+
70
+ def _nearby_workspaces(cwd, limit=3):
71
+ found = []
72
+ try:
73
+ for config in sorted(cwd.glob("*/.taskseam/config.json")) + sorted(cwd.glob("*/*/.taskseam/config.json")):
74
+ found.append(str(config.parent.parent))
75
+ if len(found) >= limit:
76
+ break
77
+ except OSError:
78
+ pass
79
+ return found
80
+
81
+
82
+ def _project(cwd):
83
+ checks = []
84
+ try:
85
+ workspace = find_workspace(cwd)
86
+ except ValueError as exc:
87
+ return [_check("fail", "Project", str(exc))]
88
+ if not workspace:
89
+ nearby = _nearby_workspaces(cwd)
90
+ if nearby:
91
+ return [_check("fail", "Project",
92
+ "{} is not inside a TaskSeam project, but these folders are: {}. Agents "
93
+ "only see state when the editor opens the project folder itself.".format(
94
+ cwd, ", ".join(nearby)),
95
+ "open one of those folders in your editor, or cd into it")]
96
+ return [_check("fail", "Project", "{} is not inside a TaskSeam project".format(cwd),
97
+ "cd your-project && taskseam init")]
98
+ root = workspace[0]
99
+ checks.append(_check("ok", "Project", str(root)))
100
+ try:
101
+ store = Store(database_path(workspace))
102
+ try:
103
+ version = store.db.execute("PRAGMA user_version").fetchone()[0]
104
+ context = store.context(active_task(workspace))
105
+ finally:
106
+ store.close()
107
+ except (ValueError, OSError) as exc:
108
+ checks.append(_check("fail", "Project state", str(exc)))
109
+ return checks
110
+ counts = {}
111
+ for item in context["items"]:
112
+ counts[item["kind"]] = counts.get(item["kind"], 0) + 1
113
+ summary = ", ".join("{} {}{}".format(counts.get(kind, 0), kind, "" if counts.get(kind, 0) == 1 else "s")
114
+ for kind in ("decision", "constraint", "question"))
115
+ checks.append(_check("ok", "Project state",
116
+ "task '{}' (schema v{}): {}".format(context["task"]["title"], version, summary)))
117
+ if version != SCHEMA_VERSION:
118
+ checks.append(_check("warn", "Project state", "schema v{} differs from v{}".format(
119
+ version, SCHEMA_VERSION)))
120
+ if not context["items"]:
121
+ checks.append(_check("warn", "Project state",
122
+ "nothing recorded yet; agents save state when you accept a decision",
123
+ 'taskseam record decision "..." --source user'))
124
+ ignore = root / ".gitignore"
125
+ lines = ignore.read_text(encoding="utf-8").splitlines() if ignore.exists() else []
126
+ if not {".taskseam/", "/.taskseam/", ".taskseam"} & {line.strip() for line in lines}:
127
+ checks.append(_check("warn", "Privacy", ".taskseam/ is not in .gitignore, so state could be committed",
128
+ "echo '.taskseam/' >> .gitignore"))
129
+ return checks
130
+
131
+
132
+ def diagnose(cwd=None, probe_mcp=True):
133
+ cwd = Path(cwd or Path.cwd()).resolve()
134
+ sections = [("TaskSeam", [_check("ok", "Installed", "{} ({})".format(__version__, sys.executable))])]
135
+ any_agent = False
136
+ for label, tool, executable, locate in AGENTS:
137
+ found, how = find_agent(executable)
138
+ if not found:
139
+ sections.append((label, [_check("info", "Installed", "not found on PATH or in an editor extension")]))
140
+ continue
141
+ any_agent = True
142
+ checks = [_check("ok", "Installed", "{} ({})".format(found, how))]
143
+ if probe_mcp:
144
+ checks.append(_mcp_registration(found, tool))
145
+ checks.append(_hook(locate(), tool))
146
+ sections.append((label, checks))
147
+ if not any_agent:
148
+ sections[0][1].append(_check("fail", "Agents", "neither Claude Code nor Codex was found",
149
+ "install Claude Code or Codex, then run taskseam setup"))
150
+ sections.append(("This folder", _project(cwd)))
151
+ return sections
152
+
153
+
154
+ SYMBOLS = {"ok": ("✓", "ok"), "warn": ("!", "!!"), "fail": ("✗", "XX"), "info": ("-", "--")}
155
+
156
+
157
+ def render(sections, stream=None):
158
+ stream = stream or sys.stdout
159
+ encoding = getattr(stream, "encoding", None) or "utf-8"
160
+ try:
161
+ "✓✗".encode(encoding)
162
+ index = 0
163
+ except (UnicodeEncodeError, LookupError):
164
+ index = 1
165
+ lines = []
166
+ for title, checks in sections:
167
+ lines.append(title)
168
+ for check in checks:
169
+ lines.append(" {} {}: {}".format(SYMBOLS[check["status"]][index], check["check"], check["detail"]))
170
+ if check["fix"] and check["status"] in ("fail", "warn"):
171
+ lines.append(" fix: " + check["fix"])
172
+ lines.append("")
173
+ problems = sum(1 for _, checks in sections for check in checks if check["status"] == "fail")
174
+ lines.append("Everything needed is in place." if not problems else
175
+ "{} problem{} found.".format(problems, "" if problems == 1 else "s"))
176
+ stream.write("\n".join(lines) + "\n")
177
+ return 1 if problems else 0
@@ -8,12 +8,12 @@ advance any agent's delivery position, so ``taskseam_continue`` deltas still wor
8
8
 
9
9
  import json
10
10
  import os
11
- import shutil
12
11
  import subprocess
13
12
  import sys
14
13
  from pathlib import Path
15
14
 
16
15
  from .render import brief
16
+ from .setup import find_agent
17
17
  from .store import Store
18
18
  from .workspace import active_task, database_path, find_workspace
19
19
 
@@ -135,8 +135,8 @@ def install_detected(python_executable=None, dry_run=False, tools=None):
135
135
  for name, executable, locate in targets:
136
136
  if tools and name not in tools:
137
137
  continue
138
- if not shutil.which(executable):
139
- skipped.append({"tool": name, "reason": "not found on PATH"})
138
+ if not find_agent(executable)[0] and not locate().parent.is_dir():
139
+ skipped.append({"tool": name, "reason": "not installed"})
140
140
  continue
141
141
  result = install(locate(), python_executable, dry_run)
142
142
  if name == "codex":
@@ -1,22 +1,59 @@
1
1
  """Configuration helpers for supported AI tools."""
2
2
 
3
+ import os
4
+ import re
3
5
  import shutil
4
6
  import subprocess
5
7
  import sys
8
+ from pathlib import Path
9
+
10
+ # Editor extensions bundle their own agent CLI. Users who only install the
11
+ # VS Code/Cursor extension have no `claude` or `codex` on PATH.
12
+ EDITOR_EXTENSION_DIRS = (".vscode/extensions", ".vscode-insiders/extensions",
13
+ ".cursor/extensions", ".windsurf/extensions")
14
+ BUNDLED = {
15
+ "claude": ("anthropic.claude-code-*", ("resources/native-binary/claude",
16
+ "resources/native-binary/claude.exe")),
17
+ "codex": ("openai.chatgpt-*", ("bin/*/codex", "bin/*/codex.exe")),
18
+ }
19
+
20
+
21
+ def _version_key(path):
22
+ match = re.search(r"-(\d+(?:\.\d+)*)", path.name)
23
+ return tuple(int(part) for part in match.group(1).split(".")) if match else ()
24
+
25
+
26
+ def find_agent(name, home=None):
27
+ """Return (executable, how_found) for an agent CLI, or (None, None)."""
28
+ on_path = shutil.which(name)
29
+ if on_path:
30
+ return on_path, "PATH"
31
+ pattern, binaries = BUNDLED[name]
32
+ home = Path(home or Path.home())
33
+ candidates = []
34
+ for base in EDITOR_EXTENSION_DIRS:
35
+ for extension in (home / base).glob(pattern):
36
+ for binary in binaries:
37
+ candidates.extend((extension, found) for found in extension.glob(binary)
38
+ if found.is_file() and os.access(str(found), os.X_OK))
39
+ if not candidates:
40
+ return None, None
41
+ extension, found = max(candidates, key=lambda pair: _version_key(pair[0]))
42
+ return str(found), "editor extension " + extension.name
6
43
 
7
44
 
8
45
  def codex_command(python_executable=None):
9
- codex = shutil.which("codex")
46
+ codex = find_agent("codex")[0]
10
47
  if not codex:
11
- raise ValueError("Codex CLI was not found on PATH")
48
+ raise ValueError("Codex was not found on PATH or in a VS Code/Cursor extension")
12
49
  python = python_executable or sys.executable
13
50
  return [codex, "mcp", "add", "taskseam", "--", python, "-m", "taskseam", "mcp"]
14
51
 
15
52
 
16
53
  def claude_command(python_executable=None):
17
- claude = shutil.which("claude")
54
+ claude = find_agent("claude")[0]
18
55
  if not claude:
19
- raise ValueError("Claude Code CLI was not found on PATH")
56
+ raise ValueError("Claude Code was not found on PATH or in a VS Code/Cursor extension")
20
57
  python = python_executable or sys.executable
21
58
  return [claude, "mcp", "add", "--scope", "user", "taskseam", "--",
22
59
  python, "-m", "taskseam", "mcp"]
@@ -68,10 +105,12 @@ def setup_detected(python_executable=None, dry_run=False):
68
105
  skipped = []
69
106
  for name, installer in installers:
70
107
  executable = "claude" if name == "claude-code" else name
71
- if not shutil.which(executable):
72
- skipped.append({"tool": name, "reason": "not found on PATH"})
108
+ found, how = find_agent(executable)
109
+ if not found:
110
+ skipped.append({"tool": name,
111
+ "reason": "not found on PATH or in a VS Code/Cursor extension"})
73
112
  continue
74
113
  result = installer(python_executable, dry_run)
75
- detected.append({"tool": name, **result})
114
+ detected.append({"tool": name, "found_via": how, **result})
76
115
  return {"configured": detected, "skipped": skipped,
77
116
  "web_assistants": "ChatGPT and Claude web support is available as a developer-preview browser extension"}
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: taskseam
3
- Version: 0.2.0
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
@@ -62,10 +62,11 @@ TaskSeam stores the current task state under the project's `.taskseam/` director
62
62
 
63
63
  ## Quick start
64
64
 
65
- Install TaskSeam as an isolated command-line application:
65
+ Install TaskSeam as an isolated command-line application, then watch it work in a throwaway project:
66
66
 
67
67
  ```bash
68
68
  pipx install taskseam
69
+ taskseam demo # one minute, no agents or settings touched
69
70
  ```
70
71
 
71
72
  Standard pip installation also works:
@@ -74,7 +75,7 @@ Standard pip installation also works:
74
75
  python3 -m pip install taskseam
75
76
  ```
76
77
 
77
- 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:
78
79
 
79
80
  ```bash
80
81
  taskseam setup
@@ -100,6 +101,7 @@ There are no routine TaskSeam commands after initialization. In Claude Code and
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:
101
102
 
102
103
  ```bash
104
+ taskseam doctor # is everything connected? prints the fix if not
103
105
  taskseam show # what every agent will see, in plain text
104
106
  taskseam drop 3f9a --reason "Offline mode cut" # retire an item that no longer applies
105
107
  taskseam export --agents-md # mirror state into AGENTS.md for non-MCP agents
@@ -4,6 +4,8 @@ pyproject.toml
4
4
  taskseam/__init__.py
5
5
  taskseam/__main__.py
6
6
  taskseam/api.py
7
+ taskseam/demo.py
8
+ taskseam/doctor.py
7
9
  taskseam/hooks.py
8
10
  taskseam/importer.py
9
11
  taskseam/mcp.py
@@ -19,6 +21,7 @@ taskseam.egg-info/top_level.txt
19
21
  tests/test_api.py
20
22
  tests/test_cli.py
21
23
  tests/test_continuity_features.py
24
+ tests/test_doctor.py
22
25
  tests/test_end_to_end.py
23
26
  tests/test_importer.py
24
27
  tests/test_mcp.py
@@ -0,0 +1,117 @@
1
+ import io
2
+ import json
3
+ import os
4
+ import subprocess
5
+ import sys
6
+ import tempfile
7
+ import unittest
8
+ from pathlib import Path
9
+ from unittest import mock
10
+
11
+ from taskseam import doctor, hooks
12
+
13
+ ROOT = Path(__file__).resolve().parents[1]
14
+
15
+
16
+ def statuses(sections):
17
+ return {(title, check["check"]): check["status"] for title, checks in sections for check in checks}
18
+
19
+
20
+ class DoctorTests(unittest.TestCase):
21
+ def setUp(self):
22
+ self.tmp = tempfile.TemporaryDirectory()
23
+ self.root = Path(self.tmp.name)
24
+ self.claude = self.root / "home" / ".claude" / "settings.json"
25
+ self.codex = self.root / "home" / ".codex" / "hooks.json"
26
+ patches = [
27
+ mock.patch("taskseam.doctor.AGENTS", (
28
+ ("Claude Code", "claude-code", "claude", lambda: self.claude),
29
+ ("Codex", "codex", "codex", lambda: self.codex))),
30
+ mock.patch("taskseam.doctor.find_agent",
31
+ side_effect=lambda name: ("/bin/" + name, "PATH") if name == "claude" else (None, None)),
32
+ ]
33
+ for patch in patches:
34
+ patch.start()
35
+ self.addCleanup(patch.stop)
36
+
37
+ def tearDown(self):
38
+ self.tmp.cleanup()
39
+
40
+ def init_project(self, name="project"):
41
+ project = self.root / name
42
+ project.mkdir()
43
+ subprocess.run([sys.executable, "-m", "taskseam", "init"], cwd=project, check=True,
44
+ capture_output=True, env={**os.environ, "PYTHONPATH": str(ROOT)})
45
+ return project
46
+
47
+ def test_healthy_setup_reports_no_problems(self):
48
+ hooks.install(self.claude, sys.executable)
49
+ project = self.init_project()
50
+ registered = mock.Mock(returncode=0, stdout=sys.executable + " -m taskseam mcp", stderr="")
51
+ with mock.patch("taskseam.doctor.subprocess.run", return_value=registered):
52
+ sections = doctor.diagnose(project)
53
+ result = statuses(sections)
54
+ self.assertEqual(result[("Claude Code", "MCP server")], "ok")
55
+ self.assertEqual(result[("Claude Code", "Session-start hook")], "ok")
56
+ self.assertEqual(result[("Codex", "Installed")], "info")
57
+ self.assertEqual(result[("This folder", "Project")], "ok")
58
+ out = io.StringIO()
59
+ self.assertEqual(doctor.render(sections, out), 0)
60
+ self.assertIn("Everything needed is in place", out.getvalue())
61
+
62
+ @mock.patch("taskseam.doctor.subprocess.run")
63
+ def test_missing_registration_hook_and_stale_python_have_fixes(self, run):
64
+ run.return_value = mock.Mock(returncode=1, stdout="", stderr="not found")
65
+ sections = doctor.diagnose(self.root)
66
+ result = statuses(sections)
67
+ self.assertEqual(result[("Claude Code", "MCP server")], "fail")
68
+ self.assertEqual(result[("Claude Code", "Session-start hook")], "fail")
69
+ hooks.install(self.claude, "/gone/python")
70
+ stale = [c for t, cs in doctor.diagnose(self.root, probe_mcp=False) for c in cs
71
+ if c["check"] == "Session-start hook"][0]
72
+ self.assertIn("no longer exists", stale["detail"])
73
+ self.assertEqual(stale["fix"], "taskseam hook install claude-code")
74
+ out = io.StringIO()
75
+ self.assertEqual(doctor.render(sections, out), 1)
76
+ self.assertIn("fix: taskseam setup claude-code", out.getvalue())
77
+
78
+ def test_wrong_folder_points_to_nearby_projects(self):
79
+ self.init_project("app")
80
+ project = [c for t, cs in doctor.diagnose(self.root, probe_mcp=False) for c in cs
81
+ if c["check"] == "Project"][0]
82
+ self.assertEqual(project["status"], "fail")
83
+ self.assertIn(str(self.root / "app"), project["detail"])
84
+
85
+ def test_privacy_warning_when_state_is_not_ignored(self):
86
+ project = self.init_project()
87
+ (project / ".gitignore").write_text("node_modules/\n")
88
+ result = statuses(doctor.diagnose(project, probe_mcp=False))
89
+ self.assertEqual(result[("This folder", "Privacy")], "warn")
90
+
91
+ def test_ascii_fallback_for_limited_consoles(self):
92
+ class Ascii(io.StringIO):
93
+ encoding = "ascii"
94
+ out = Ascii()
95
+ doctor.render([("X", [doctor._check("fail", "Thing", "broken", "fix it")])], out)
96
+ self.assertIn("XX Thing", out.getvalue())
97
+
98
+
99
+ class DemoTests(unittest.TestCase):
100
+ def test_demo_tells_the_story_and_cleans_up(self):
101
+ from taskseam.demo import run
102
+ out = io.StringIO()
103
+ with mock.patch("taskseam.demo.tempfile.TemporaryDirectory",
104
+ wraps=tempfile.TemporaryDirectory) as temporary:
105
+ self.assertEqual(run(pause=0, stream=out), 0)
106
+ text = out.getvalue()
107
+ self.assertIn("+ decision: Export invoices as CSV, not PDF", text)
108
+ self.assertIn("- decision: Export invoices as PDF", text)
109
+ hook_part = text.split("session-start hook")[1].split("Back in Claude Code")[0]
110
+ self.assertNotIn("Export invoices as PDF\n", hook_part)
111
+ self.assertIn("RFC 4180", hook_part)
112
+ created = temporary.call_args.kwargs.get("prefix")
113
+ self.assertEqual(created, "taskseam-demo-")
114
+
115
+
116
+ if __name__ == "__main__":
117
+ unittest.main()
@@ -1,7 +1,10 @@
1
+ import os
2
+ import tempfile
1
3
  import unittest
4
+ from pathlib import Path
2
5
  from unittest import mock
3
6
 
4
- from taskseam.setup import (claude_command, codex_command, setup_claude,
7
+ from taskseam.setup import (claude_command, codex_command, find_agent, setup_claude,
5
8
  setup_codex, setup_detected)
6
9
 
7
10
 
@@ -47,15 +50,45 @@ class SetupTests(unittest.TestCase):
47
50
 
48
51
  @mock.patch("taskseam.setup.setup_claude")
49
52
  @mock.patch("taskseam.setup.setup_codex")
50
- @mock.patch("taskseam.setup.shutil.which")
51
- def test_auto_setup_configures_only_detected_tools(self, which, codex, claude):
52
- which.side_effect = lambda name: "/tools/codex" if name == "codex" else None
53
+ @mock.patch("taskseam.setup.find_agent")
54
+ def test_auto_setup_configures_only_detected_tools(self, find, codex, claude):
55
+ find.side_effect = lambda name: ("/tools/codex", "PATH") if name == "codex" else (None, None)
53
56
  codex.return_value = {"configured": True}
54
57
  result = setup_detected("/venv/bin/python")
55
- self.assertEqual(result["configured"], [{"tool": "codex", "configured": True}])
58
+ self.assertEqual(result["configured"],
59
+ [{"tool": "codex", "found_via": "PATH", "configured": True}])
56
60
  self.assertEqual(result["skipped"][0]["tool"], "claude-code")
57
61
  claude.assert_not_called()
58
62
 
59
63
 
64
+ class FindAgentTests(unittest.TestCase):
65
+ def make_binary(self, path):
66
+ path.parent.mkdir(parents=True, exist_ok=True)
67
+ path.write_text("#!/bin/sh\n")
68
+ os.chmod(str(path), 0o755)
69
+
70
+ @mock.patch("taskseam.setup.shutil.which", return_value=None)
71
+ def test_finds_newest_bundled_editor_binary(self, _which):
72
+ with tempfile.TemporaryDirectory() as home:
73
+ ext = Path(home) / ".vscode" / "extensions"
74
+ self.make_binary(ext / "anthropic.claude-code-2.1.9-darwin-arm64" /
75
+ "resources" / "native-binary" / "claude")
76
+ newest = (Path(home) / ".cursor" / "extensions" /
77
+ "anthropic.claude-code-2.1.10-darwin-arm64" / "resources" / "native-binary" / "claude")
78
+ self.make_binary(newest)
79
+ self.make_binary(ext / "openai.chatgpt-26.1117.4-darwin-arm64" / "bin" / "macos-aarch64" / "codex")
80
+ found, how = find_agent("claude", home)
81
+ self.assertEqual(found, str(newest))
82
+ self.assertIn("2.1.10", how)
83
+ self.assertTrue(find_agent("codex", home)[0].endswith("codex"))
84
+
85
+ @mock.patch("taskseam.setup.shutil.which", return_value="/usr/local/bin/claude")
86
+ def test_path_wins_and_missing_returns_none(self, _which):
87
+ self.assertEqual(find_agent("claude"), ("/usr/local/bin/claude", "PATH"))
88
+ with mock.patch("taskseam.setup.shutil.which", return_value=None), \
89
+ tempfile.TemporaryDirectory() as home:
90
+ self.assertEqual(find_agent("codex", home), (None, None))
91
+
92
+
60
93
  if __name__ == "__main__":
61
94
  unittest.main()
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes