agent-shared-context 0.1.0__tar.gz

agent_shared_context-0.1.0/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pip show:*)"
+    ]
+  }
+}

agent_shared_context-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/

agent_shared_context-0.1.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: agent-shared-context
+Version: 0.1.0
+Summary: Personal work orchestrator. One CLI, one main context, many agents.
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: claude-agent-sdk
+Requires-Dist: pyyaml
+Description-Content-Type: text/markdown
+
+# asc
+
+Agent Shared Context. One CLI, one main context, many agents.
+
+asc is a protocol for agents to share context. When an agent finishes work, it registers a zero-loss brief. Your main thread stays coherent across every tool, every agent, every project.
+
+## Install
+
+```
+uv tool install agent-shared-context
+```
+
+Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+## The protocol
+
+When you're done with a task, register a zero-loss brief:
+
+```
+echo "<zero-loss-brief>" | asc register --author <name>
+```
+
+A zero-loss brief is **complete** (every decision, artifact, loose end), **concise** (dense, not long), and **concrete** (specific paths, names, states — actionable).
+
+That's the protocol. Put it in your CLAUDE.md, your Cursor rules, your AGENTS.md. Any agent that can run a shell command can follow it.
+
+## Commands
+
+```
+asc where are we                          # talk to the main thread
+asc run claude debug the migration issue  # dispatch an agent
+asc run --ro claude research k8s networking  # read-only dispatch
+echo "<brief>" | asc register --author gemini  # register a handoff
+```
+
+## How it works
+
+- **`asc <message>`** — talk to your main thread. Read-only. It knows everything that's been registered and synthesizes it for you.
+- **`asc run <agent> <task>`** — dispatch an agent. It works, then registers a zero-loss brief when done.
+- **`asc register --author <name>`** — the universal write API. Any agent, any surface, anywhere.
+
+Context is stored as YAML day files in `~/.asc/days/`. Not per-project. Your entire work environment.
+
+## License
+
+MIT

agent_shared_context-0.1.0/README.md

@@ -0,0 +1,46 @@
+# asc
+
+Agent Shared Context. One CLI, one main context, many agents.
+
+asc is a protocol for agents to share context. When an agent finishes work, it registers a zero-loss brief. Your main thread stays coherent across every tool, every agent, every project.
+
+## Install
+
+```
+uv tool install agent-shared-context
+```
+
+Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+
+## The protocol
+
+When you're done with a task, register a zero-loss brief:
+
+```
+echo "<zero-loss-brief>" | asc register --author <name>
+```
+
+A zero-loss brief is **complete** (every decision, artifact, loose end), **concise** (dense, not long), and **concrete** (specific paths, names, states — actionable).
+
+That's the protocol. Put it in your CLAUDE.md, your Cursor rules, your AGENTS.md. Any agent that can run a shell command can follow it.
+
+## Commands
+
+```
+asc where are we                          # talk to the main thread
+asc run claude debug the migration issue  # dispatch an agent
+asc run --ro claude research k8s networking  # read-only dispatch
+echo "<brief>" | asc register --author gemini  # register a handoff
+```
+
+## How it works
+
+- **`asc <message>`** — talk to your main thread. Read-only. It knows everything that's been registered and synthesizes it for you.
+- **`asc run <agent> <task>`** — dispatch an agent. It works, then registers a zero-loss brief when done.
+- **`asc register --author <name>`** — the universal write API. Any agent, any surface, anywhere.
+
+Context is stored as YAML day files in `~/.asc/days/`. Not per-project. Your entire work environment.
+
+## License
+
+MIT

agent_shared_context-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-shared-context"
+version = "0.1.0"
+description = "Personal work orchestrator. One CLI, one main context, many agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "claude-agent-sdk",
+    "pyyaml",
+]
+
+[project.scripts]
+asc = "asc.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/asc"]

agent_shared_context-0.1.0/src/asc/chat.py

@@ -0,0 +1,98 @@
+"""Chat agent — the main thread interface."""
+
+import asyncio
+import sys
+
+from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
+from claude_agent_sdk.types import StreamEvent, ToolUseBlock
+
+from asc.context import ContextItem, append_item, load_recent_items
+from asc.ui import format_items, print_step, tool_label, spin, CYAN, RESET
+
+SYSTEM_PROMPT = """\
+You are the main thread agent for asc — a personal work orchestrator.
+
+You are the user's central context. You know what's been happening across all their work: \
+dispatched agents, registrations, conversations. You synthesize it all and respond concisely.
+
+When the user asks "where are we" or "what's going on" — you give them the real picture. \
+Not a dump. A crisp, coherent status based on everything you know.
+
+You speak directly. No fluff. You remember prior context and build on it.
+
+## Current context
+{context}"""
+
+
+async def _chat_async(message: str) -> None:
+    items = load_recent_items()
+    context = format_items(items)
+    system = SYSTEM_PROMPT.format(context=context)
+
+    append_item(ContextItem.now(author="user", type="dialogue", content=message))
+
+    options = ClaudeAgentOptions(
+        system_prompt=system,
+        allowed_tools=["Read", "Glob", "Grep", "WebSearch", "WebFetch"],
+        max_turns=10,
+    )
+
+    full_text = ""
+    printed_len = 0
+    spinner_task = asyncio.create_task(spin())
+    spinning = True
+
+    def _stop_spinner():
+        nonlocal spinning
+        if not spinning:
+            return
+        spinning = False
+        spinner_task.cancel()
+        sys.stdout.write("\r\033[2K")
+        sys.stdout.flush()
+
+    def _start_spinner():
+        nonlocal spinning, spinner_task
+        if spinning:
+            return
+        spinning = True
+        spinner_task = asyncio.create_task(spin())
+
+    try:
+        async for msg in query(prompt=message, options=options):
+            if isinstance(msg, StreamEvent):
+                event = msg.event
+                if event.get("type") == "content_block_delta":
+                    delta = event.get("delta", {})
+                    if delta.get("type") == "text_delta":
+                        _stop_spinner()
+                        new_text = delta.get("text", "")
+                        full_text += new_text
+                        print(f"{CYAN}{new_text}{RESET}", end="", flush=True)
+                        printed_len += len(new_text)
+            elif isinstance(msg, AssistantMessage):
+                for block in msg.content:
+                    if isinstance(block, ToolUseBlock):
+                        _stop_spinner()
+                        print_step(tool_label(block))
+                        # Reset for next turn — text will be new
+                        printed_len = 0
+                        _start_spinner()
+                    elif isinstance(block, TextBlock):
+                        _stop_spinner()
+                        if len(block.text) > printed_len:
+                            remaining = block.text[printed_len:]
+                            print(f"{CYAN}{remaining}{RESET}", end="", flush=True)
+                        full_text = block.text
+    finally:
+        _stop_spinner()
+
+    if full_text:
+        print()
+
+    append_item(ContextItem.now(author="claude", type="dialogue", content=full_text.strip()))
+
+
+def chat(message: str) -> None:
+    """Send a message to the main thread agent, stream the response."""
+    asyncio.run(_chat_async(message))

agent_shared_context-0.1.0/src/asc/cli.py

@@ -0,0 +1,68 @@
+"""CLI entry point for asc."""
+
+import sys
+
+from asc.chat import chat
+from asc.register import register
+from asc.ui import YELLOW, RESET
+
+
+def main():
+    args = sys.argv[1:]
+
+    if not args:
+        print(f"{YELLOW}asc — personal work orchestrator{RESET}")
+        print()
+        print("  asc <message>                    talk to the main thread")
+        print("  asc register --author <name>     register a zero-loss brief")
+        print("  asc run <agent> <task>           dispatch an agent")
+        print("  asc run --ro <agent> <task>      dispatch read-only agent")
+        sys.exit(0)
+
+    if args[0] == "register":
+        author = None
+        rest = args[1:]
+
+        if "--author" in rest:
+            idx = rest.index("--author")
+            if idx + 1 < len(rest):
+                author = rest[idx + 1]
+                rest = rest[:idx] + rest[idx + 2:]
+            else:
+                print(f"{YELLOW}error: --author requires a name{RESET}")
+                sys.exit(1)
+
+        text = " ".join(rest) if rest else None
+        register(author=author, text=text)
+
+    elif args[0] == "run":
+        rest = args[1:]
+        read_only = False
+
+        if "--ro" in rest:
+            read_only = True
+            rest.remove("--ro")
+
+        if len(rest) < 2:
+            print(f"{YELLOW}usage: asc run <agent> <task>{RESET}")
+            sys.exit(1)
+
+        agent = rest[0]
+        task = " ".join(rest[1:])
+
+        from asc.dispatch import dispatch
+        try:
+            dispatch(agent=agent, task=task, read_only=read_only)
+        except KeyboardInterrupt:
+            print(f"\n{YELLOW}dispatch interrupted.{RESET}")
+
+    else:
+        message = " ".join(args)
+        try:
+            chat(message)
+        except KeyboardInterrupt:
+            print()
+
+
+if __name__ == "__main__":
+    main()

agent_shared_context-0.1.0/src/asc/context.py

@@ -0,0 +1,73 @@
+"""Context item data model and day file management."""
+
+import os
+from dataclasses import dataclass, asdict, field
+from datetime import datetime, date
+from pathlib import Path
+
+import yaml
+
+ASC_DIR = Path.home() / ".asc"
+DAYS_DIR = ASC_DIR / "days"
+
+
+@dataclass
+class ContextItem:
+    author: str
+    date: str
+    type: str
+    content: str
+    cwd: str | None = field(default=None)
+
+    @staticmethod
+    def now(author: str, type: str, content: str, cwd: str | None = None) -> "ContextItem":
+        return ContextItem(
+            author=author,
+            date=datetime.now().astimezone().isoformat(),
+            type=type,
+            content=content,
+            cwd=cwd or os.getcwd(),
+        )
+
+
+def _ensure_dirs():
+    DAYS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _today_file() -> Path:
+    return DAYS_DIR / f"{date.today().isoformat()}.yaml"
+
+
+def append_item(item: ContextItem) -> None:
+    """Append a context item to today's day file."""
+    _ensure_dirs()
+    path = _today_file()
+
+    items = load_day(path)
+    items.append(asdict(item))
+
+    with open(path, "w") as f:
+        yaml.dump(items, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
+
+
+def load_day(path: Path) -> list[dict]:
+    """Load all items from a day file."""
+    if not path.exists():
+        return []
+    with open(path) as f:
+        data = yaml.safe_load(f)
+    return data if isinstance(data, list) else []
+
+
+def load_recent_items() -> list[dict]:
+    """Load raw items from today and yesterday."""
+    _ensure_dirs()
+    today = date.today()
+    yesterday = date.fromordinal(today.toordinal() - 1)
+
+    items = []
+    for d in [yesterday, today]:
+        path = DAYS_DIR / f"{d.isoformat()}.yaml"
+        items.extend(load_day(path))
+
+    return items

agent_shared_context-0.1.0/src/asc/dispatch.py

@@ -0,0 +1,110 @@
+"""Dispatch — run agents with context and step printing."""
+
+import asyncio
+import os
+
+from claude_agent_sdk import (
+    ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock,
+    tool, create_sdk_mcp_server,
+)
+from claude_agent_sdk.types import StreamEvent, ToolUseBlock
+
+from asc.context import ContextItem, append_item, load_recent_items
+from asc.ui import format_items, print_step, tool_label, CYAN, YELLOW, RESET
+
+READ_ONLY_TOOLS = ["Read", "Glob", "Grep", "WebSearch", "WebFetch"]
+
+ZLB_DEFINITION = """\
+A zero-loss brief follows three rules:
+- Complete — every decision, every artifact, every loose end
+- Concise — dense, not long
+- Concrete — specific paths, names, states. Actionable."""
+
+DISPATCH_SYSTEM_PROMPT = """\
+You are a dispatched agent working on a specific task.
+
+## Your task
+{task}
+
+## Context from the main thread
+{context}
+
+## When you're done
+Write a zero-loss brief and register it using the asc_register tool.
+
+{zlb_definition}
+
+Do your work, then register. Every time."""
+
+READ_ONLY_ADDENDUM = """
+
+## Read-only mode
+You are in read-only mode. Do NOT create, edit, or delete any files. \
+You may only read files, search, and browse the web."""
+
+
+def _make_register_tool(agent: str):
+    @tool("asc_register", "Register a zero-loss brief to the main context.", {"brief": str})
+    async def asc_register(args):
+        append_item(ContextItem.now(
+            author=agent,
+            type="registration",
+            content=args["brief"],
+        ))
+        return {"content": [{"type": "text", "text": "registered."}]}
+
+    return asc_register
+
+
+async def _dispatch_async(agent: str, task: str, read_only: bool) -> None:
+    items = load_recent_items()
+    context = format_items(items)
+
+    system = DISPATCH_SYSTEM_PROMPT.format(
+        task=task,
+        context=context,
+        agent=agent,
+        zlb_definition=ZLB_DEFINITION,
+    )
+
+    register_tool = _make_register_tool(agent)
+    asc_server = create_sdk_mcp_server("asc", tools=[register_tool])
+
+    if read_only:
+        system += READ_ONLY_ADDENDUM
+        options = ClaudeAgentOptions(
+            system_prompt=system,
+            cwd=os.getcwd(),
+            allowed_tools=[*READ_ONLY_TOOLS, "mcp__asc__asc_register"],
+            mcp_servers={"asc": asc_server},
+        )
+    else:
+        options = ClaudeAgentOptions(
+            system_prompt=system,
+            cwd=os.getcwd(),
+            permission_mode="bypassPermissions",
+            mcp_servers={"asc": asc_server},
+        )
+
+    print_step(f"Starting: {task}", prefix=agent, color=YELLOW)
+
+    async with ClaudeSDKClient(options=options) as client:
+        await client.query(task)
+
+        async for msg in client.receive_response():
+            if isinstance(msg, AssistantMessage):
+                for block in msg.content:
+                    if isinstance(block, TextBlock) and block.text.strip():
+                        print(f"{CYAN}{block.text}{RESET}", flush=True)
+                    elif isinstance(block, ToolUseBlock):
+                        print_step(tool_label(block), prefix=agent)
+
+            elif isinstance(msg, StreamEvent):
+                pass  # streaming deltas — agent text already handled above
+
+    print_step("Done.", prefix=agent, color=YELLOW)
+
+
+def dispatch(agent: str, task: str, read_only: bool = False) -> None:
+    """Dispatch an agent to work on a task."""
+    asyncio.run(_dispatch_async(agent, task, read_only))

agent_shared_context-0.1.0/src/asc/register.py

@@ -0,0 +1,32 @@
+"""Register command — universal write API to the main context."""
+
+import sys
+
+from asc.context import ContextItem, append_item
+from asc.ui import YELLOW, MAGENTA, RESET
+
+
+def register(author: str | None = None, text: str | None = None) -> None:
+    """Register a zero-loss brief to the main context.
+
+    Canonical usage: echo "<zero-loss-brief>" | asc register --author gemini
+    """
+    if text:
+        content = text
+    elif not sys.stdin.isatty():
+        content = sys.stdin.read().strip()
+    else:
+        print(f"{YELLOW}usage: echo '<zero-loss-brief>' | asc register --author <name>{RESET}")
+        print(f"{YELLOW}       asc register --author <name> <text>{RESET}")
+        sys.exit(1)
+
+    if not content:
+        print(f"{YELLOW}error: empty registration{RESET}")
+        sys.exit(1)
+
+    append_item(ContextItem.now(
+        author=author or "agent",
+        type="registration",
+        content=content,
+    ))
+    print(f"{MAGENTA}registered.{RESET}")

agent_shared_context-0.1.0/src/asc/ui.py

@@ -0,0 +1,70 @@
+"""Shared UI helpers — spinners, step printing, tool labels."""
+
+import asyncio
+import sys
+
+from claude_agent_sdk.types import ToolUseBlock
+
+# ANSI color constants
+CYAN = "\033[36m"
+YELLOW = "\033[33m"
+MAGENTA = "\033[35m"
+DIM = "\033[2m"
+RESET = "\033[0m"
+
+SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+
+def format_items(items: list[dict]) -> str:
+    if not items:
+        return "(no activity yet)"
+
+    lines = []
+    for item in items:
+        author = item.get("author", "unknown")
+        date = item.get("date", "")
+        type_ = item.get("type", "")
+        content = item.get("content", "")
+        cwd = item.get("cwd", "")
+        prefix = f"[{date}] ({type_}) {author}"
+        if cwd:
+            prefix += f" [{cwd}]"
+        lines.append(f"{prefix}: {content}")
+    return "\n".join(lines)
+
+
+def print_step(msg: str, prefix: str | None = None, color: str = DIM):
+    label = f"[{prefix}] {msg}" if prefix else f"  {msg}"
+    print(f"{color}{label}{RESET}", flush=True)
+
+
+def tool_label(block: ToolUseBlock) -> str:
+    """Build a short human-readable label for a tool call."""
+    name = block.name
+    inp = block.input or {}
+
+    if name == "WebSearch":
+        return f"Searching: {inp.get('query', '')[:80]}"
+    if name == "WebFetch":
+        return f"Fetching: {inp.get('url', '')[:80]}"
+    if name == "Bash":
+        return f"Running: {inp.get('command', '')[:80]}"
+    if name in ("Read", "Glob", "Grep"):
+        target = inp.get("file_path") or inp.get("pattern") or inp.get("path", "")
+        return f"{name}: {target[:80]}"
+    if name in ("Edit", "Write"):
+        return f"{name}: {inp.get('file_path', '')}"
+    return name
+
+
+async def spin():
+    i = 0
+    try:
+        while True:
+            frame = SPINNER_FRAMES[i % len(SPINNER_FRAMES)]
+            sys.stdout.write(f"\r{CYAN}{frame}{RESET} ")
+            sys.stdout.flush()
+            i += 1
+            await asyncio.sleep(0.08)
+    except asyncio.CancelledError:
+        pass