taskmanager-exe 0.3.1__py3-none-any.whl

taskman/__init__.py

@@ -0,0 +1 @@
+"""TaskManager package."""

taskman/cli.py

@@ -0,0 +1,93 @@
+import argparse
+
+from taskman import core
+
+
+def _get_version() -> str:
+    try:
+        from importlib.metadata import version
+        return version("taskmanager-exe")
+    except Exception:
+        return "dev"
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="taskman")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {_get_version()}")
+    subparsers = parser.add_subparsers(dest="command")
+
+    # Setup commands
+    subparsers.add_parser("init")
+    install_mcp = subparsers.add_parser("install-mcp")
+    install_mcp.add_argument("agent", choices=["claude", "cursor", "codex"])
+    install_skills = subparsers.add_parser("install-skills")
+    install_skills.add_argument("agent", choices=["claude", "codex"])
+    uninstall_mcp = subparsers.add_parser("uninstall-mcp")
+    uninstall_mcp.add_argument("agent", choices=["claude", "cursor", "codex"])
+    uninstall_skills = subparsers.add_parser("uninstall-skills")
+    uninstall_skills.add_argument("agent", choices=["claude", "codex"])
+    subparsers.add_parser("stdio")
+
+    wt_parser = subparsers.add_parser("wt")
+    wt_parser.add_argument("name", nargs="?", default=None,
+                           help="worktree name (omit to just clone .agent-files in current dir)")
+    wt_parser.add_argument("--new", dest="new_branch", action="store_true",
+                           help="create new branch instead of using existing one")
+
+    # Operation commands
+    desc = subparsers.add_parser("describe")
+    desc.add_argument("reason")
+
+    sy = subparsers.add_parser("sync")
+    sy.add_argument("reason")
+
+    hd = subparsers.add_parser("history-diffs")
+    hd.add_argument("file")
+    hd.add_argument("start_rev")
+    hd.add_argument("end_rev", nargs="?", default="@")
+
+    hb = subparsers.add_parser("history-batch")
+    hb.add_argument("file")
+    hb.add_argument("start_rev")
+    hb.add_argument("end_rev", nargs="?", default="@")
+
+    hs = subparsers.add_parser("history-search")
+    hs.add_argument("pattern")
+    hs.add_argument("--file", default=None)
+    hs.add_argument("--limit", type=int, default=20)
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        print(core.init())
+    elif args.command == "wt":
+        print(core.wt(args.name, new_branch=args.new_branch))
+    elif args.command == "install-mcp":
+        print(core.install_mcp(args.agent))
+    elif args.command == "install-skills":
+        print(core.install_skills(args.agent))
+    elif args.command == "uninstall-mcp":
+        print(core.uninstall_mcp(args.agent))
+    elif args.command == "uninstall-skills":
+        print(core.uninstall_skills(args.agent))
+    elif args.command == "stdio":
+        from taskman.server import main as server_main
+
+        server_main()
+    elif args.command == "describe":
+        print(core.describe(args.reason))
+    elif args.command == "sync":
+        print(core.sync(args.reason))
+    elif args.command == "history-diffs":
+        print(core.history_diffs(args.file, args.start_rev, args.end_rev))
+    elif args.command == "history-batch":
+        print(core.history_batch(args.file, args.start_rev, args.end_rev))
+    elif args.command == "history-search":
+        print(core.history_search(args.pattern, args.file, args.limit))
+    else:
+        parser.print_help()
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

taskman/core.py

@@ -0,0 +1,579 @@
+import json
+import re
+import shutil
+import subprocess
+from pathlib import Path
+import tomllib
+
+from taskman.jj import run_jj, find_agent_files_dir
+
+
+def _run_cmd(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
+    proc = subprocess.run(
+        args,
+        cwd=str(cwd) if cwd is not None else None,
+        text=True,
+        capture_output=True,
+    )
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+def _run_cmd_check(args: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
+    code, out, err = _run_cmd(args, cwd=cwd)
+    if code != 0:
+        cmd_str = " ".join(args)
+        raise RuntimeError(
+            f"command failed ({code}): {cmd_str}\nstdout:\n{out}\nstderr:\n{err}"
+        )
+    return code, out, err
+
+
+def _agent_files_cwd() -> Path:
+    return find_agent_files_dir()
+
+
+def _current_rev_id(cwd: Path) -> str:
+    _, out, _ = run_jj(
+        ["log", "--no-graph", "-r", "@", "-T", "change_id.short()"],
+        cwd,
+    )
+    return out.strip()
+
+
+def _has_remote_main(cwd: Path) -> bool:
+    try:
+        run_jj(["log", "-r", "main@origin", "--no-graph", "-T", "commit_id"], cwd)
+    except RuntimeError:
+        return False
+    return True
+
+
+def _is_main_tracked(cwd: Path) -> bool:
+    """Check if main@origin is tracked (linked to local main)."""
+    _, out, _ = run_jj(["bookmark", "list", "--all"], cwd)
+    # Tracked: "main: xyz abc" with "main@origin" on separate line
+    # Untracked: "main@origin [new] untracked"
+    for line in out.splitlines():
+        if "main@origin" in line and "untracked" in line:
+            return False
+    return True
+
+
+def _setup_main_bookmark(cwd: Path) -> None:
+    """Ensure main bookmark exists, tracks main@origin, and points to @."""
+    # Track main@origin if exists and untracked
+    if _has_remote_main(cwd) and not _is_main_tracked(cwd):
+        run_jj(["bookmark", "track", "main@origin"], cwd)
+
+    # Set main bookmark to current revision (creates if doesn't exist)
+    try:
+        run_jj(["bookmark", "set", "main", "-r", "@"], cwd)
+    except RuntimeError as exc:
+        # If bookmark doesn't exist, create it
+        if "no such bookmark" in str(exc).lower():
+            run_jj(["bookmark", "create", "main", "-r", "@"], cwd)
+        else:
+            raise
+
+
+def _status_has_conflicts(status_out: str) -> bool:
+    return bool(re.search(r"(?im)^(conflicts|conflicted)\b", status_out))
+
+
+def _rev_list_for_revset(revset: str, cwd: Path) -> list[str]:
+    _, out, _ = run_jj(
+        ["log", "--no-graph", "-r", revset, "-T", 'change_id.short() ++ "\\n"'],
+        cwd,
+    )
+    return [line.strip() for line in out.splitlines() if line.strip()]
+
+
+def _revset_has_revs(revset: str, cwd: Path) -> bool:
+    return bool(_rev_list_for_revset(revset, cwd))
+
+
+def _rev_list(start_rev: str, end_rev: str, cwd: Path) -> list[str]:
+    if _revset_has_revs(start_rev, cwd):
+        revset = f"{start_rev}::{end_rev}"
+    else:
+        revset = f"::{end_rev}"
+    return _rev_list_for_revset(revset, cwd)
+
+
+def _escape_revset_value(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', "\\\"")
+
+
+def describe(reason: str) -> str:
+    """Create named checkpoint.
+
+    1. jj status (trigger snapshot)
+    2. jj describe -m "<reason>"
+
+    Returns: Revision ID and confirmation
+    """
+    cwd = _agent_files_cwd()
+    run_jj(["status"], cwd)
+    run_jj(["describe", "-m", reason], cwd)
+    rev = _current_rev_id(cwd)
+    return f"described {rev}: {reason}"
+
+
+def sync(reason: str) -> str:
+    """Full sync: describe, fetch, rebase, push.
+
+    1. jj describe -m "<reason>"
+    2. jj git fetch
+    3. jj rebase -d main@origin (skip if no remote branch)
+    4. Check jj status for conflicts -> return if conflicts
+    5. jj git push -> return error if rejected
+
+    Returns: Step-by-step status or conflict info
+    """
+    cwd = _agent_files_cwd()
+    steps: list[str] = []
+
+    run_jj(["describe", "-m", reason], cwd)
+    rev = _current_rev_id(cwd)
+    steps.append(f"rev: {rev}")
+
+    run_jj(["git", "fetch"], cwd)
+    steps.append("git fetch: ok")
+
+    has_remote = _has_remote_main(cwd)
+    if has_remote:
+        run_jj(["rebase", "-d", "main@origin"], cwd)
+        steps.append("rebase: main@origin")
+    else:
+        steps.append("rebase: skipped (no main@origin)")
+
+    _, status_out, _ = run_jj(["status"], cwd)
+    if _status_has_conflicts(status_out):
+        return "conflicts detected:\n" + status_out
+
+    _setup_main_bookmark(cwd)
+
+    try:
+        # Use --all for first push (no remote yet), regular push otherwise
+        push_cmd = ["git", "push"] if has_remote else ["git", "push", "--all"]
+        run_jj(push_cmd, cwd)
+        steps.append("git push: ok")
+    except RuntimeError as exc:
+        err_msg = str(exc)
+        steps.append("git push: FAILED")
+        # Extract useful info from jj error
+        if "no author" in err_msg.lower() or "no committer" in err_msg.lower():
+            steps.append("Error: commit has no author/committer set")
+            steps.append("Fix: jj config set --user user.name 'Your Name'")
+            steps.append("     jj config set --user user.email 'you@example.com'")
+        elif "rejected" in err_msg.lower() or "non-fast-forward" in err_msg.lower():
+            steps.append("Error: push rejected (remote changed)")
+            steps.append("Recovery: run 'taskman sync' again to rebase and retry")
+        else:
+            steps.append(err_msg)
+        return "\n".join(steps)
+
+    return "\n".join(steps)
+
+
+def history_diffs(file: str, start_rev: str, end_rev: str = "@") -> str:
+    """Get all diffs for file across revision range.
+
+    1. Get revisions: jj log --no-graph -r "{start}::{end}" -T 'change_id.short()'
+    2. For each: jj diff -r {rev} -- {file}
+    3. Concatenate with === {rev} === headers
+    """
+    cwd = _agent_files_cwd()
+    revs = _rev_list(start_rev, end_rev, cwd)
+    if not revs:
+        return "No revisions found in range."
+
+    sections: list[str] = []
+    for rev in revs:
+        sections.append(f"=== {rev} ===")
+        _, out, _ = run_jj(["diff", "-r", rev, "--", file], cwd)
+        sections.append(out.rstrip())
+
+    return "\n".join(sections).rstrip()
+
+
+def history_batch(file: str, start_rev: str, end_rev: str = "@") -> str:
+    """Fetch file content at all revisions in range.
+
+    1. Get revisions (same as history_diffs)
+    2. For each: jj file show -r {rev} {file}
+    3. Concatenate with === {rev} === headers
+    """
+    cwd = _agent_files_cwd()
+    revs = _rev_list(start_rev, end_rev, cwd)
+    if not revs:
+        return "No revisions found in range."
+
+    sections: list[str] = []
+    for rev in revs:
+        try:
+            _, out, _ = run_jj(["file", "show", "-r", rev, file], cwd)
+        except RuntimeError as exc:
+            if "no such path" in str(exc).lower():
+                sections.append(f"=== {rev} ===")
+                sections.append("(file does not exist at this revision)")
+                continue
+            raise
+        sections.append(f"=== {rev} ===")
+        sections.append(out.rstrip())
+
+    return "\n".join(sections).rstrip()
+
+
+def history_search(pattern: str, file: str | None = None, limit: int = 20) -> str:
+    """Search history for pattern in diffs using jj's diff_contains().
+
+    Uses: jj log -r 'diff_contains("{pattern}")' --limit {limit}
+    Or with file: jj log -r 'diff_contains("{pattern}", "{file}")' --limit {limit}
+
+    Supports jj pattern syntax: exact:, glob:, regex:, substring:
+    Examples:
+      history_search("TODO")                    # glob (default)
+      history_search("regex:fix.*bug")          # regex
+      history_search("exact:FIXME", "src/")     # exact match in src/
+
+    Returns: Matching revisions with commit info
+    """
+    cwd = _agent_files_cwd()
+    escaped_pattern = _escape_revset_value(pattern)
+    if file is None:
+        revset = f'diff_contains("{escaped_pattern}")'
+    else:
+        escaped_file = _escape_revset_value(file)
+        revset = f'diff_contains("{escaped_pattern}", "{escaped_file}")'
+    _, out, _ = run_jj(["log", "-r", revset, "--limit", str(limit)], cwd)
+    return out.rstrip()
+
+
+# Setup functions
+
+def init() -> str:
+    """Create .agent-files.git/ (bare) + .agent-files/ (clone)
+
+    1. git init --bare .agent-files.git
+    2. jj git clone .agent-files.git .agent-files
+    3. Create initial files: STATUS.md, LONGTERM_MEM.md, MEDIUMTERM_MEM.md, tasks/
+    4. jj describe -m "initial setup" && jj git push
+    """
+    cwd = Path.cwd()
+    bare = cwd / ".agent-files.git"
+    clone = cwd / ".agent-files"
+
+    if bare.exists() or clone.exists():
+        raise FileExistsError(".agent-files.git or .agent-files already exists")
+
+    _run_cmd_check(["git", "init", "--bare", str(bare)], cwd=cwd)
+    run_jj(["git", "clone", str(bare), str(clone)], cwd)
+
+    # Set default author for agent commits
+    run_jj(["config", "set", "--repo", "user.name", "Agent"], clone)
+    run_jj(["config", "set", "--repo", "user.email", "agent@localhost"], clone)
+
+    (clone / "tasks").mkdir(parents=True, exist_ok=True)
+    for filename in ["STATUS.md", "LONGTERM_MEM.md", "MEDIUMTERM_MEM.md"]:
+        path = clone / filename
+        path.touch(exist_ok=True)
+
+    run_jj(["describe", "-m", "initial setup"], clone)
+    run_jj(["bookmark", "create", "main", "-r", "@"], clone)
+    run_jj(["git", "push", "--all"], clone)
+
+    return "Initialized .agent-files.git and .agent-files"
+
+
+def _find_agent_files_git_dir(start: Path | None = None) -> Path:
+    current = Path.cwd() if start is None else Path(start)
+    if current.is_file():
+        current = current.parent
+
+    while True:
+        candidate = current / ".agent-files.git"
+        if candidate.is_dir():
+            return candidate
+        if current.parent == current:
+            break
+        current = current.parent
+
+    raise FileNotFoundError(".agent-files.git directory not found")
+
+
+def wt(name: str | None = None, *, new_branch: bool = False) -> str:
+    """Create git worktree and/or clone .agent-files
+
+    If name is provided (from main repo):
+        1. Create worktrees/<name>/ via git worktree add
+        2. Clone .agent-files into worktrees/<name>/
+
+    If name is None (recovery for existing worktree):
+        1. Clone .agent-files into current directory
+
+    By default uses existing branch. If new_branch=True, creates new branch.
+    """
+    cwd = Path.cwd()
+    origin = _find_agent_files_git_dir(cwd)
+    in_main_repo = (cwd / ".agent-files.git").exists()
+
+    if name:
+        if not in_main_repo:
+            raise ValueError(
+                f"Run 'taskman wt {name}' from main repo ({origin.parent})"
+            )
+        worktree_dir = cwd / "worktrees" / name
+        if worktree_dir.exists():
+            raise FileExistsError(f"worktrees/{name} already exists")
+
+        cmd = ["git", "worktree", "add", str(worktree_dir)]
+        if not new_branch:
+            cmd.append(name)
+        _run_cmd_check(cmd, cwd=cwd)
+
+        clone = worktree_dir / ".agent-files"
+        run_jj(["git", "clone", str(origin), str(clone)], worktree_dir)
+        run_jj(["config", "set", "--repo", "user.name", "Agent"], clone)
+        run_jj(["config", "set", "--repo", "user.email", "agent@localhost"], clone)
+
+        return f"Created worktree at worktrees/{name}/"
+    else:
+        if in_main_repo:
+            raise ValueError("Use 'taskman wt <name>' to create a worktree")
+        clone = cwd / ".agent-files"
+        if clone.exists():
+            raise FileExistsError(".agent-files already exists")
+        run_jj(["git", "clone", str(origin), str(clone)], cwd)
+        run_jj(["config", "set", "--repo", "user.name", "Agent"], clone)
+        run_jj(["config", "set", "--repo", "user.email", "agent@localhost"], clone)
+        return f"Cloned .agent-files from {origin}"
+
+
+def _load_json(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    text = path.read_text(encoding="utf-8")
+    if not text.strip():
+        return {}
+    return json.loads(text)
+
+
+def _write_json(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def _load_toml(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    text = path.read_text(encoding="utf-8")
+    if not text.strip():
+        return {}
+    return tomllib.loads(text)
+
+
+def _toml_format_value(value) -> str:
+    if isinstance(value, str):
+        escaped = value.replace("\\", "\\\\").replace('"', "\\\"")
+        return f"\"{escaped}\""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return repr(value)
+    if isinstance(value, list):
+        return "[" + ", ".join(_toml_format_value(v) for v in value) + "]"
+    raise TypeError(f"Unsupported TOML value: {value!r}")
+
+
+def _toml_dump_table(lines: list[str], prefix: list[str], table: dict) -> None:
+    lines.append(f"[{'.'.join(prefix)}]")
+    for key in sorted(table.keys()):
+        value = table[key]
+        if isinstance(value, dict):
+            continue
+        lines.append(f"{key} = {_toml_format_value(value)}")
+
+    for key in sorted(table.keys()):
+        value = table[key]
+        if isinstance(value, dict):
+            lines.append("")
+            _toml_dump_table(lines, prefix + [key], value)
+
+
+def _toml_dumps(data: dict) -> str:
+    lines: list[str] = []
+
+    for key in sorted(data.keys()):
+        value = data[key]
+        if isinstance(value, dict):
+            continue
+        lines.append(f"{key} = {_toml_format_value(value)}")
+
+    for key in sorted(data.keys()):
+        value = data[key]
+        if isinstance(value, dict):
+            if lines:
+                lines.append("")
+            _toml_dump_table(lines, [key], value)
+
+    if not lines:
+        return ""
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def install_mcp(agent: str) -> str:
+    """Install MCP config for agent (claude, cursor, codex).
+
+    Config locations:
+    - claude: ~/.claude.json or .mcp.json (adds to mcpServers)
+    - cursor: ~/.cursor/mcp.json (adds to mcpServers)
+    - codex: ~/.codex/config.toml (adds to mcp_servers)
+    """
+    home = Path.home()
+    if agent == "claude":
+        project_config = Path(".mcp.json")
+        path = project_config if project_config.exists() else home / ".claude.json"
+        data = _load_json(path)
+        data.setdefault("mcpServers", {})
+        data["mcpServers"]["taskman"] = {
+            "type": "stdio",
+            "command": "taskman",
+            "args": ["stdio"],
+        }
+        _write_json(path, data)
+        return f"Installed taskman MCP server in {path}"
+
+    if agent == "cursor":
+        project_config = Path(".cursor") / "mcp.json"
+        path = project_config if project_config.exists() else home / ".cursor" / "mcp.json"
+        data = _load_json(path)
+        data.setdefault("mcpServers", {})
+        data["mcpServers"]["taskman"] = {
+            "type": "stdio",
+            "command": "taskman",
+            "args": ["stdio"],
+        }
+        _write_json(path, data)
+        return f"Installed taskman MCP server in {path}"
+
+    if agent == "codex":
+        path = home / ".codex" / "config.toml"
+        data = _load_toml(path)
+        data.setdefault("mcp_servers", {})
+        data["mcp_servers"]["taskman"] = {
+            "command": "taskman",
+            "args": ["stdio"],
+        }
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(_toml_dumps(data), encoding="utf-8")
+        return f"Installed taskman MCP server in {path}"
+
+    raise ValueError(f"Unknown agent: {agent}")
+
+
+def install_skills(agent: str) -> str:
+    """Copy skill files to agent's skills directory."""
+    skills_dir = Path(__file__).resolve().parent / "skills"
+    if not skills_dir.is_dir():
+        raise FileNotFoundError(f"skills directory not found: {skills_dir}")
+
+    home = Path.home()
+    if agent == "claude":
+        dest_dir = home / ".claude" / "skills" / "taskman"
+    elif agent == "codex":
+        dest_dir = home / ".codex" / "skills" / "taskman"
+    else:
+        raise ValueError(f"Unknown agent: {agent}")
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+
+    count = 0
+    for path in skills_dir.glob("*.md"):
+        shutil.copy2(path, dest_dir / path.name)
+        count += 1
+
+    return f"Installed {count} skills to {dest_dir}"
+
+
+def uninstall_mcp(agent: str) -> str:
+    """Remove MCP config for agent (claude, cursor, codex)."""
+    home = Path.home()
+    if agent == "claude":
+        project_config = Path(".mcp.json")
+        path = project_config if project_config.exists() else home / ".claude.json"
+        if not path.exists():
+            return f"No MCP config found at {path}"
+        data = _load_json(path)
+        servers = data.get("mcpServers")
+        if isinstance(servers, dict) and "taskman" in servers:
+            servers.pop("taskman", None)
+            if servers:
+                data["mcpServers"] = servers
+            else:
+                data.pop("mcpServers", None)
+            _write_json(path, data)
+            return f"Removed taskman MCP server from {path}"
+        return f"No taskman MCP server entry found in {path}"
+
+    if agent == "cursor":
+        project_config = Path(".cursor") / "mcp.json"
+        path = project_config if project_config.exists() else home / ".cursor" / "mcp.json"
+        if not path.exists():
+            return f"No MCP config found at {path}"
+        data = _load_json(path)
+        servers = data.get("mcpServers")
+        if isinstance(servers, dict) and "taskman" in servers:
+            servers.pop("taskman", None)
+            if servers:
+                data["mcpServers"] = servers
+            else:
+                data.pop("mcpServers", None)
+            _write_json(path, data)
+            return f"Removed taskman MCP server from {path}"
+        return f"No taskman MCP server entry found in {path}"
+
+    if agent == "codex":
+        path = home / ".codex" / "config.toml"
+        if not path.exists():
+            return f"No MCP config found at {path}"
+        data = _load_toml(path)
+        servers = data.get("mcp_servers")
+        if isinstance(servers, dict) and "taskman" in servers:
+            servers.pop("taskman", None)
+            if servers:
+                data["mcp_servers"] = servers
+            else:
+                data.pop("mcp_servers", None)
+            path.write_text(_toml_dumps(data), encoding="utf-8")
+            return f"Removed taskman MCP server from {path}"
+        return f"No taskman MCP server entry found in {path}"
+
+    raise ValueError(f"Unknown agent: {agent}")
+
+
+def uninstall_skills(agent: str) -> str:
+    """Remove taskman skill files from agent's skills directory."""
+    home = Path.home()
+    if agent == "claude":
+        dest_dir = home / ".claude" / "skills" / "taskman"
+    elif agent == "codex":
+        dest_dir = home / ".codex" / "skills" / "taskman"
+    else:
+        raise ValueError(f"Unknown agent: {agent}")
+
+    if not dest_dir.is_dir():
+        return f"No skills directory found at {dest_dir}"
+
+    count = 0
+    for path in dest_dir.glob("*.md"):
+        path.unlink()
+        count += 1
+
+    # Remove the taskman directory if empty
+    if dest_dir.is_dir() and not any(dest_dir.iterdir()):
+        dest_dir.rmdir()
+
+    return f"Removed {count} skills from {dest_dir}"

taskman/jj.py

@@ -0,0 +1,76 @@
+import shlex
+import subprocess
+from pathlib import Path
+
+
+def run_jj(args: list[str], cwd: Path) -> tuple[int, str, str]:
+    """Run jj command with git conflict style.
+
+    Uses --config-toml when supported, otherwise falls back to --config.
+    Uses subprocess.run() - no async needed for sequential CLI commands.
+
+    Returns: (returncode, stdout, stderr)
+    Raises: RuntimeError if returncode != 0
+    """
+    cmd_toml = [
+        "jj",
+        "--config-toml",
+        'ui.conflict-marker-style = "git"',
+        *args,
+    ]
+    proc = subprocess.run(
+        cmd_toml,
+        cwd=str(cwd),
+        text=True,
+        capture_output=True,
+    )
+    if proc.returncode != 0 and "unexpected argument '--config-toml'" in proc.stderr:
+        cmd_legacy = [
+            "jj",
+            "--config",
+            "ui.conflict-marker-style=git",
+            *args,
+        ]
+        proc = subprocess.run(
+            cmd_legacy,
+            cwd=str(cwd),
+            text=True,
+            capture_output=True,
+        )
+        if proc.returncode != 0:
+            message = (
+                f"jj command failed ({proc.returncode}): {shlex.join(cmd_legacy)}\n"
+                f"stdout:\n{proc.stdout}\n"
+                f"stderr:\n{proc.stderr}"
+            )
+            raise RuntimeError(message)
+        return proc.returncode, proc.stdout, proc.stderr
+
+    if proc.returncode != 0:
+        message = (
+            f"jj command failed ({proc.returncode}): {shlex.join(cmd_toml)}\n"
+            f"stdout:\n{proc.stdout}\n"
+            f"stderr:\n{proc.stderr}"
+        )
+        raise RuntimeError(message)
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+def find_agent_files_dir(start: Path | None = None) -> Path:
+    """Search upward from start (default: cwd) to find .agent-files/
+
+    Returns: Path to .agent-files/ or raises FileNotFoundError
+    """
+    current = Path.cwd() if start is None else Path(start)
+    if current.is_file():
+        current = current.parent
+
+    while True:
+        candidate = current / ".agent-files"
+        if candidate.is_dir():
+            return candidate
+        if current.parent == current:
+            break
+        current = current.parent
+
+    raise FileNotFoundError(".agent-files directory not found")

taskman/server.py

@@ -0,0 +1,56 @@
+import asyncio
+from mcp.server.fastmcp import FastMCP
+
+from taskman import core
+
+
+class _SyncMCP:
+    def __init__(self, inner: FastMCP) -> None:
+        self._inner = inner
+
+    def list_tools(self):
+        return asyncio.run(self._inner.list_tools())
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+
+mcp = _SyncMCP(FastMCP("taskman"))
+
+
+@mcp.tool()
+def describe(reason: str) -> str:
+    """Create named checkpoint."""
+    return core.describe(reason)
+
+
+@mcp.tool()
+def sync(reason: str) -> str:
+    """Full sync: describe, fetch, rebase, push."""
+    return core.sync(reason)
+
+
+@mcp.tool()
+def history_diffs(file: str, start_rev: str, end_rev: str = "@") -> str:
+    """Get all diffs for file across revision range."""
+    return core.history_diffs(file, start_rev, end_rev)
+
+
+@mcp.tool()
+def history_batch(file: str, start_rev: str, end_rev: str = "@") -> str:
+    """Fetch file content at all revisions in range."""
+    return core.history_batch(file, start_rev, end_rev)
+
+
+@mcp.tool()
+def history_search(pattern: str, file: str | None = None, limit: int = 20) -> str:
+    """Search history for pattern in diffs."""
+    return core.history_search(pattern, file, limit)
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

taskman/skills/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: taskman
+description: Agent memory and task management CLI. Use this skill when you need to persist context across sessions, track tasks, hand off work, or store temporary agent scratch data. Provides the `taskman` CLI for init, sync, describe, and history operations.
+---
+
+# Taskman
+
+Version-controlled agent memory and task management. The `.agent-files/` directory is scratch space for ANY agent work that should persist across sessions - task tracking, memory, handoffs, notes, or temporary files.
+
+## Structure
+
+```
+.agent-files/
+  STATUS.md           # Task index, current session state
+  LONGTERM_MEM.md     # Architecture knowledge (months+)
+  MEDIUMTERM_MEM.md   # Patterns, gotchas (weeks)
+  tasks/
+    TASK_<slug>.md    # Active tasks
+    _archive/         # Completed tasks
+  (any other scratch files)
+```
+
+**STATUS.md**: Operational state - task index, current focus, blockers, next steps. Update, don't overwrite.
+
+**LONGTERM_MEM.md**: System architecture, component relationships. Rarely changes.
+
+**MEDIUMTERM_MEM.md**: Reusable patterns and gotchas. NOT session logs.
+
+**Task files**: One per user-facing work unit. Format:
+
+```markdown
+# TASK: <title>
+
+## Meta
+Status: planned|in_progress|blocked|complete
+Priority: P0|P1|P2
+Created: YYYY-MM-DD
+Completed: YYYY-MM-DD
+
+## Problem
+<what, why>
+
+## Design
+<decisions, alternatives rejected>
+
+## Checklist
+- [ ] item
+- [x] completed item
+
+## Attempts
+### Attempt N (YYYY-MM-DD HH:MM)
+Approach: ...
+Result: ...
+
+## Summary
+Current state: ...
+Key learnings: ...
+Next steps: ...
+
+## Notes
+<breadcrumbs - pointers to recoverable info>
+
+## Budget (optional)
+Estimate: <tokens> (planning: X, impl: Y, validation: Z)
+Variance: low|med|high
+Intervention: autonomous|checkpoints|steering|collaborative
+Spent: <tokens>
+```
+
+Budget uses tokens (measurable) not time. Variance = estimate spread (low=tight, high=wide). Intervention = human engagement pattern, not duration.
+
+**Scratch space**: Store any temporary agent work here - it's version-controlled separately from the main repo.
+
+## Progressive Disclosure
+
+Store breadcrumbs (pointers), not content. Recover on-demand via Read/Bash/WebFetch.
+
+```
+<slug>: <recovery-instruction>
+```
+
+Examples: `auth-flow: src/auth/login.ts:45-80` | `build-status: run `make build`` | `prev-attempt: jj diff -r @--`
+
+Store inline only: decisions, key insights, non-reproducible errors.
+
+See `/handoff` for writing breadcrumbs, `/continue` for expanding them.
+
+## Commands
+
+| Command | Use when |
+|---------|----------|
+| /continue | Resuming work from a previous session |
+| /handoff | Saving context mid-task for next session |
+| /remember | Persisting learnings to memory files |
+| /complete | Finishing and archiving a task |
+| /sync | Syncing .agent-files with origin |
+| /describe | Creating a named checkpoint |
+| /history-search | Searching history for patterns |
+| /history-diffs | Viewing diffs across revisions |
+| /history-batch | Fetching file content at revisions |
+| /wt | Setting up .agent-files in a git worktree |
+
+When a command is invoked, read the corresponding `.md` file in this skill directory for detailed instructions.
+
+## jj Snapshotting
+
+jj does NOT auto-snapshot on file changes alone. A jj command must be run to trigger a snapshot. Run `jj st` periodically (after edits or batches of edits) to capture history. Without this, intermediate states are lost.
+
+## Important
+
+`.agent-files/` should never be committed. Add it to `.gitignore`.

taskman/skills/complete.md

@@ -0,0 +1,16 @@
+Complete a task and archive it.
+
+1. Update the task file:
+   - Set Status: complete
+   - Add Completed: date
+   - Fill Notes with any gotchas or uncompleted work
+
+2. Move task to _archive/
+
+3. Update STATUS.md:
+   - Remove from active tasks
+   - Add pointer to next task (if any)
+
+4. Run: taskman sync "complete: $ARGUMENTS"
+
+Keep it brief - the task is done.

taskman/skills/continue.md

@@ -0,0 +1,28 @@
+Resume work from a previous session.
+
+1. Run: taskman sync "continue"
+
+2. Read STATUS.md - current focus, blockers, task index
+
+3. Read the active task file(s) - focus on Summary and Notes sections
+
+4. **Expand breadcrumbs selectively** (see below)
+
+5. Ultrathink about your approach before continuing.
+
+## Expanding Breadcrumbs
+
+Task files contain pointers, not content. Expand only what's needed for your next step:
+
+| Breadcrumb | Recovery |
+|------------|----------|
+| `src/auth.ts:45-80` | Read tool (those lines only) |
+| run \`pytest -v\` | Bash tool (current state) |
+| `jj diff -r @--` | Bash tool (last changes) |
+| `issue: github.com/...` | WebFetch if needed |
+
+**Order:** Read summary → identify next step → expand only what's needed → work → repeat.
+
+Don't preload all references upfront. The previous session left good pointers - trust them and expand lazily.
+
+**Ultrathink vs preloading:** Think deeply about *approach*, not by dumping all content into context. Expand breadcrumbs to answer specific questions, not "just in case".

taskman/skills/describe.md

@@ -0,0 +1,5 @@
+Create a named checkpoint in .agent-files.
+
+Run: taskman describe "$ARGUMENTS"
+
+Report the revision ID.

taskman/skills/handoff.md

@@ -0,0 +1,43 @@
+Mid-task handoff - save detailed context for next session.
+
+1. Update the current task file with:
+   - Attempts: what was tried, what failed (brief - just approach + outcome)
+   - Summary: current state, key learnings, next steps
+   - Notes: **breadcrumbs only** - pointers to recoverable information
+   - Budget: update Spent tokens if tracking
+
+2. Run: taskman sync "handoff: $ARGUMENTS"
+
+3. Update STATUS.md with handoff context (brief pointer to task file)
+
+## Breadcrumb Principle
+
+**Store pointers, not content.** The next session can recover information on-demand.
+
+Bad (context pollution):
+```markdown
+## Notes
+The authentication flow works like this:
+[50 lines of code]
+The error message was:
+[20 lines of stack trace]
+```
+
+Good (progressive disclosure):
+```markdown
+## Notes
+auth-flow: src/auth/login.ts:45-80
+error-repro: run `make test-auth` (fails on line 23)
+prev-diff: jj diff -r @--
+related-issue: github.com/org/repo/issues/123
+```
+
+## Writing Breadcrumbs
+
+Format: `<slug>: <recovery-instruction> [(context)]`
+
+Recovery: file→Read, command→Bash, url→WebFetch
+
+**Store inline** (not as breadcrumbs): decisions, key insights, non-reproducible errors.
+
+Goal: next session reconstructs context in 2-3 tool calls, not by reading walls of text.

taskman/skills/history-batch.md

@@ -0,0 +1,7 @@
+Fetch file content at all revisions in range.
+
+Arguments: <file> <start_rev> [end_rev]
+
+Run: taskman history-batch $ARGUMENTS
+
+Display the output.

taskman/skills/history-diffs.md

@@ -0,0 +1,7 @@
+Get all diffs for a file across revisions.
+
+Arguments: <file> <start_rev> [end_rev]
+
+Run: taskman history-diffs $ARGUMENTS
+
+Display the output.

taskman/skills/history-search.md

@@ -0,0 +1,13 @@
+Search history for a pattern in diffs.
+
+Arguments: <pattern> [--file <file>] [--limit N]
+
+Pattern syntax (jj native):
+- Default: glob match
+- regex:pattern - regex match
+- exact:pattern - exact match
+- substring:pattern - substring match
+
+Run: taskman history-search $ARGUMENTS
+
+Display matching revisions.

taskman/skills/remember.md

@@ -0,0 +1,8 @@
+Persist context to memory files.
+
+1. Update appropriate file based on $ARGUMENTS:
+   - MEDIUMTERM_MEM.md: patterns, gotchas, recent learnings
+   - LONGTERM_MEM.md: architecture, component relationships
+   - STATUS.md: current state, blockers, next steps
+
+2. Run: taskman sync "remember: $ARGUMENTS"

taskman/skills/sync.md

@@ -0,0 +1,5 @@
+Sync .agent-files with origin.
+
+Run: taskman sync "$ARGUMENTS"
+
+If conflicts are reported, help the user resolve them with Edit, then run sync again.

taskman/skills/wt.md

@@ -0,0 +1,9 @@
+Set up .agent-files in a git worktree.
+
+Run: taskman wt $ARGUMENTS
+
+- No arguments: clone .agent-files into current directory (for existing worktrees)
+- `taskman wt <name>`: create worktree for existing branch <name>
+- `taskman wt <name> --new`: create worktree + new branch at worktrees/<name>/
+
+Use when working in a git worktree that doesn't have .agent-files yet.

taskmanager_exe-0.3.1.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: taskmanager-exe
+Version: 0.3.1
+Summary: Version-controlled task management for AI agents
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: mcp
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TaskManager.exe
+
+Version-controlled task management for AI agents. Agents use familiar file editing tools; versioning and sync happen transparently via [jj (jujutsu)](https://martinvonz.github.io/jj/).
+
+## Problem
+
+AI agents using file-based task systems lose work when:
+- Multiple agents edit the same file
+- Context resets mid-task and overwrites with stale state
+- No history to recover from
+- **Agents go in circles** - after context reset, they repeat mistakes because they don't know what was already tried
+
+## Installation
+
+Requires Python 3.11+ and [jj](https://martinvonz.github.io/jj/latest/install/).
+
+```bash
+pipx install taskmanager-exe
+# or
+uvx taskmanager-exe
+```
+
+## Quick Start
+
+```bash
+# Initialize in your repo
+taskman init
+
+# Install MCP server config
+taskman install-mcp claude    # or: cursor, codex
+
+# Install Claude Code skills (optional)
+taskman install-skills
+```
+
+To create a worktree (from main repo):
+```bash
+taskman wt my-feature    # creates worktrees/my-feature/ + clones .agent-files
+```
+
+To add .agent-files to an existing worktree (recovery):
+```bash
+taskman wt               # clones .agent-files into current directory
+```
+
+## How It Works
+
+```
+Agent
+  │
+  ├── Edit tool ────────► .agent-files/ (jj repo)
+  │   (file ops)                │
+  │                        push/pull
+  ├── MCP Server ───────────────┼──────────────────►
+  │   (batch/sync)              ▼
+  │                     .agent-files.git/ (bare origin)
+  └── Skills ───────────────────┘
+      (CLI wrapper)
+```
+
+- Agents edit files with their normal Edit tool
+- jj auto-snapshots every change (no explicit commit needed)
+- MCP tools or Skills handle sync and history queries
+- Bare git origin serializes concurrent access across worktrees
+
+## CLI Commands
+
+```bash
+taskman init                    # create .agent-files.git/ + .agent-files/
+taskman wt <name>               # create worktree (from main repo)
+taskman wt                      # add .agent-files to existing worktree
+taskman install-mcp <agent>     # install MCP config (claude, cursor, codex)
+taskman install-skills          # install skill files to ~/.claude/commands/
+taskman uninstall-mcp <agent>   # remove MCP config
+taskman uninstall-skills        # remove skill files
+
+taskman describe <reason>       # create named checkpoint
+taskman sync <reason>           # full sync: describe + fetch + rebase + push
+taskman history-diffs <file> <start> [end]    # diffs across revision range
+taskman history-batch <file> <start> [end]    # file content at each revision
+taskman history-search <pattern> [file] [limit]  # search history
+
+taskman stdio                   # run MCP server (stdio transport)
+```
+
+## MCP Tools
+
+When installed via `taskman install-mcp`, these tools are available:
+
+| Tool | Description |
+|------|-------------|
+| `describe(reason)` | Create named checkpoint |
+| `sync(reason)` | Full sync workflow |
+| `history_diffs(file, start, end)` | Aggregate diffs across range |
+| `history_batch(file, start, end)` | File content at all revisions |
+| `history_search(pattern, file, limit)` | Search history for pattern |
+
+## Skills
+
+When installed via `taskman install-skills`, these Claude Code skills are available:
+
+| Skill | Description |
+|-------|-------------|
+| `/continue` | Resume work - pull + read STATUS.md |
+| `/handoff` | Mid-task handoff - sync + detailed context |
+| `/complete` | Task done - sync + archive |
+| `/describe <reason>` | Create named checkpoint |
+| `/sync <reason>` | Full sync workflow |
+| `/history-diffs <file> <start> [end]` | Diffs across range |
+| `/history-batch <file> <start> [end]` | File content at revisions |
+| `/history-search <pattern> [--file] [--limit]` | Search history |
+
+Skills wrap the CLI and work without MCP support.
+
+## Direct jj Commands
+
+Agents can also use jj directly for simple operations:
+
+```bash
+jj status                    # current state
+jj log                       # view history
+jj diff                      # see changes
+jj restore --from <rev> <file>  # restore file from revision
+```
+
+## Task File Structure
+
+```
+.agent-files/
+  STATUS.md           # Task index, session state
+  LONGTERM_MEM.md     # Architecture (months+)
+  MEDIUMTERM_MEM.md   # Patterns, gotchas (weeks)
+  tasks/
+    TASK_<slug>.md    # Individual tasks
+    _archive/         # Completed tasks
+```
+
+## Sync Model
+
+Sync at task boundaries:
+- `/continue` - session start, pull latest state
+- `/handoff` - mid-task, push with detailed context
+- `/complete` - task done, push and archive
+
+On conflict, agent resolves with Edit tool, then syncs again.
+
+## License
+
+MIT

taskmanager_exe-0.3.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+taskman/__init__.py,sha256=_TflS09UJqi5AVigsi628jsaSPinpUxYDMBsis-kYaU,27
+taskman/cli.py,sha256=NsadNr9OnngqOH_7nkR-6kDpYJ6kecjmbOWt9XF4eEw,3364
+taskman/core.py,sha256=du1dhUipOqV7ook5H6fEFRM_g1XebBHBtzaSnJFPB_0,19422
+taskman/jj.py,sha256=aF7W8MtxqbfRqVcmIAHVqEAW8S5B__u29QUOvlURipE,2267
+taskman/server.py,sha256=5ACffRaSZRUuPpoaheiBsVqaMLacYZeRPc9erGJCyoE,1279
+taskman/skills/SKILL.md,sha256=lvTofHeN4GwCsMmhjX5wZ_ZzanYhW1S4NtXFJB-MHpc,3467
+taskman/skills/complete.md,sha256=2A5yZ2VowIvfdYkV0vSmYLa94HZJneTyQzmDmdjEG-U,360
+taskman/skills/continue.md,sha256=aDXGWK9nP4xr9qiHzsvwuvS0osW90rMdM0GeMxL5M3s,1055
+taskman/skills/describe.md,sha256=CICVO3o0C7Fj2Pdw_Y2RVwHc11JMtevExrGtY7uTSTI,104
+taskman/skills/handoff.md,sha256=9LdtnLrSzVCkBNVYkawyUNzsoOMkh_c7N4UX1Kve9Fs,1262
+taskman/skills/history-batch.md,sha256=_X_VS7mvsx6UZchXk1LaLBcu8O1OqNxH6RPBBtB_dTY,147
+taskman/skills/history-diffs.md,sha256=3AiwkCJVnRJ-pdtbzY6uqxveW4eGjZNGOQfU6VgF5Tc,144
+taskman/skills/history-search.md,sha256=StXlsDSEOZp4Z4sJzBhUcSqJz2kNPtEgvwRMwlF0i0k,307
+taskman/skills/remember.md,sha256=47FLqmxR1nFKN6R7nlvV3ZyTd78acAQs-ZMqEHzF_JI,299
+taskman/skills/sync.md,sha256=WYLiTzl_Rb4_2aWpmaW8sHYNWwOkMOTTPAQjGcFIt0M,150
+taskman/skills/wt.md,sha256=N0-mCOl3z44q3R3XsXqmO6Mrm_CSSWuLu-WU1dOpSLs,368
+taskmanager_exe-0.3.1.dist-info/METADATA,sha256=i8qsRndysDYwoHYKC7wIOJL7akcb-clXpCXKCEC82xQ,5034
+taskmanager_exe-0.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+taskmanager_exe-0.3.1.dist-info/entry_points.txt,sha256=_S_GgMwhqTBXOPeevUXw0_Y7iOauQLIsLaC9bECTIy4,45
+taskmanager_exe-0.3.1.dist-info/licenses/LICENSE,sha256=GrA0izm2N5Ifdndiu7vcBjKqIE4varKiDt3LLqY5wPA,164
+taskmanager_exe-0.3.1.dist-info/RECORD,,

taskmanager_exe-0.3.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

taskmanager_exe-0.3.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+taskman = taskman.cli:main

taskmanager_exe-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,3 @@
+This is 100% (or maybe 99.5%) AI-generated code. It is free! You may do with it what you want!
+
+I TAKE ZERO RESPONSIBILITY FOR ANYTHING THIS CODE DOES! IT IS SLOP!