deepagent-code 0.2.0__tar.gz → 0.3.0__tar.gz

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagent-code
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Claude Code-style CLI for running LangGraph agents from the terminal
 Author-email: Kedar Dabhadkar <kdabhadk@gmail.com>
 License-Expression: MIT
@@ -19,7 +19,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: langgraph>=0.2.0
-Requires-Dist: langgraph-stream-parser<0.3,>=0.2
+Requires-Dist: langgraph-stream-parser<0.3,>=0.2.2
 Requires-Dist: click>=8.0.0
 Requires-Dist: python-dotenv
 Requires-Dist: deepagents
@@ -27,7 +27,7 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: ruff==0.15.15; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: license-file
 
@@ -37,6 +37,19 @@ A Claude Code-style CLI for running LangGraph agents from the terminal.
 
 ![deepagent-code](examples/image.png)
 
+## One agent, every surface
+
+deepagent-code is the terminal surface of the **deep-agent family**: write your agent once — any LangGraph `CompiledGraph` — and run it on every surface with the same spec string (`module:attr` or `path/to/file.py:attr`), the same `deepagents.toml` config file, and the same `DEEPAGENT_*` environment variables.
+
+| Surface | Package | Try it |
+|---|---|---|
+| Web app | [cowork-dash](https://github.com/dkedar7/cowork-dash) | `cowork-dash run --agent my_agent.py:graph` |
+| JupyterLab | [deepagent-lab](https://github.com/dkedar7/deepagent-lab) | `pip install deepagent-lab`, then the chat sidebar in `jupyter lab` |
+| Terminal | deepagent-code | **you are here** |
+| VS Code | [deepagent-vscode](https://github.com/dkedar7/deepagent-vscode) | chat participant + stdio sidecar |
+| Reference agent | [deepagent-hermes](https://github.com/dkedar7/deepagent-hermes) | `DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph` on any surface |
+| Shared core | [langgraph-stream-parser](https://github.com/dkedar7/langgraph-stream-parser) | typed events + config resolver behind every surface |
+
 ## Installation
 
 ```bash
@@ -50,6 +63,11 @@ pip install git+https://github.com/dkedar7/deepagent-code.git
 
 ## Quick Start
 
+No agent or API key yet? See the CLI working in one command:
+```bash
+deepagent-code --demo "hello"
+```
+
 Run with the default agent (requires `ANTHROPIC_API_KEY`):
 ```bash
 export ANTHROPIC_API_KEY="your_api_key"
@@ -86,6 +104,13 @@ deepagent-code --no-interactive
 
 # Verbose output
 deepagent-code -v
+
+# Keyless demo agent (no API key needed)
+deepagent-code --demo
+
+# Print the resolved configuration: each value, its source, and the
+# env var / deepagents.toml key that sets it
+deepagent-code --show-config
 ```
 
 ## Commands
@@ -99,7 +124,8 @@ In the interactive loop:
 
 ```bash
 # Agent location (path/to/file.py:variable_name or module:variable)
-export DEEPAGENT_SPEC="my_agent.py:graph"
+# (DEEPAGENT_SPEC is still accepted as a deprecated alias)
+export DEEPAGENT_AGENT_SPEC="my_agent.py:graph"
 deepagent-code
 
 # Working directory

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/README.md

@@ -4,6 +4,19 @@ A Claude Code-style CLI for running LangGraph agents from the terminal.
 
 ![deepagent-code](examples/image.png)
 
+## One agent, every surface
+
+deepagent-code is the terminal surface of the **deep-agent family**: write your agent once — any LangGraph `CompiledGraph` — and run it on every surface with the same spec string (`module:attr` or `path/to/file.py:attr`), the same `deepagents.toml` config file, and the same `DEEPAGENT_*` environment variables.
+
+| Surface | Package | Try it |
+|---|---|---|
+| Web app | [cowork-dash](https://github.com/dkedar7/cowork-dash) | `cowork-dash run --agent my_agent.py:graph` |
+| JupyterLab | [deepagent-lab](https://github.com/dkedar7/deepagent-lab) | `pip install deepagent-lab`, then the chat sidebar in `jupyter lab` |
+| Terminal | deepagent-code | **you are here** |
+| VS Code | [deepagent-vscode](https://github.com/dkedar7/deepagent-vscode) | chat participant + stdio sidecar |
+| Reference agent | [deepagent-hermes](https://github.com/dkedar7/deepagent-hermes) | `DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph` on any surface |
+| Shared core | [langgraph-stream-parser](https://github.com/dkedar7/langgraph-stream-parser) | typed events + config resolver behind every surface |
+
 ## Installation
 
 ```bash
@@ -17,6 +30,11 @@ pip install git+https://github.com/dkedar7/deepagent-code.git
 
 ## Quick Start
 
+No agent or API key yet? See the CLI working in one command:
+```bash
+deepagent-code --demo "hello"
+```
+
 Run with the default agent (requires `ANTHROPIC_API_KEY`):
 ```bash
 export ANTHROPIC_API_KEY="your_api_key"
@@ -53,6 +71,13 @@ deepagent-code --no-interactive
 
 # Verbose output
 deepagent-code -v
+
+# Keyless demo agent (no API key needed)
+deepagent-code --demo
+
+# Print the resolved configuration: each value, its source, and the
+# env var / deepagents.toml key that sets it
+deepagent-code --show-config
 ```
 
 ## Commands
@@ -66,7 +91,8 @@ In the interactive loop:
 
 ```bash
 # Agent location (path/to/file.py:variable_name or module:variable)
-export DEEPAGENT_SPEC="my_agent.py:graph"
+# (DEEPAGENT_SPEC is still accepted as a deprecated alias)
+export DEEPAGENT_AGENT_SPEC="my_agent.py:graph"
 deepagent-code
 
 # Working directory

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/deepagent_code/cli.py

@@ -2,8 +2,8 @@
 CLI for running arbitrary LangGraph agents from the terminal.
 Styled after Claude Code / nanocode.
 """
+
 import asyncio
-import importlib.util
 import json
 import os
 import re
@@ -15,6 +15,16 @@ import uuid
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+import click
+
+from langgraph_stream_parser import (
+    prepare_agent_input,
+    stream_graph_updates,
+    astream_graph_updates,
+    load_agent_spec,
+)
+from deepagent_code import config as config_module
+
 # Platform-specific imports for keyboard input
 IS_WINDOWS = sys.platform == "win32"
 if IS_WINDOWS:
@@ -23,23 +33,14 @@ else:
     import termios
     import tty
 
-import click
-
 # Try to import readline for tab completion (not available on all platforms)
 try:
     import readline
+
     HAS_READLINE = True
 except ImportError:
     HAS_READLINE = False
 
-from langgraph_stream_parser import (
-    prepare_agent_input,
-    stream_graph_updates,
-    astream_graph_updates,
-    load_agent_spec,
-)
-from deepagent_code import config as config_module
-
 
 # ANSI color codes (matching nanocode style)
 RESET, BOLD, DIM = "\033[0m", "\033[1m", "\033[2m"
@@ -154,6 +155,7 @@ def register_command(
     usage: Optional[str] = None,
 ):
     """Decorator to register a slash command handler."""
+
     def decorator(func):
         command = SlashCommand(
             name=name,
@@ -164,6 +166,7 @@ def register_command(
         )
         command_registry.register(command)
         return func
+
     return decorator
 
 
@@ -183,7 +186,11 @@ class Spinner:
             frame = SPINNER_FRAMES[self.frame_idx % len(SPINNER_FRAMES)]
             elapsed = time.time() - self.start_time
             elapsed_str = f"{int(elapsed)}s"
-            print(f"\r{CYAN}{frame}{RESET} {DIM}{self.message}... {elapsed_str}{RESET}", end="", flush=True)
+            print(
+                f"\r{CYAN}{frame}{RESET} {DIM}{self.message}... {elapsed_str}{RESET}",
+                end="",
+                flush=True,
+            )
             self.frame_idx += 1
             time.sleep(0.08)
 
@@ -246,13 +253,13 @@ def print_goodbye():
 def get_agent_name(graph) -> str:
     """Extract agent name from graph object, defaulting to 'AgentCode'."""
     # Try common attribute names for agent/graph name
-    for attr in ('name', 'agent_name', '_name', '__name__'):
+    for attr in ("name", "agent_name", "_name", "__name__"):
         if hasattr(graph, attr):
             name = getattr(graph, attr)
             if name and isinstance(name, str):
                 return name
     # Check if it's a compiled graph with a name in builder
-    if hasattr(graph, 'builder') and hasattr(graph.builder, 'name'):
+    if hasattr(graph, "builder") and hasattr(graph.builder, "name"):
         name = graph.builder.name
         if name and isinstance(name, str):
             return name
@@ -262,13 +269,13 @@ def get_agent_name(graph) -> str:
 def get_agent_description(graph) -> Optional[str]:
     """Extract agent description from graph object, if available."""
     # Try common attribute names for agent description
-    for attr in ('description', 'agent_description', '_description', '__doc__'):
+    for attr in ("description", "agent_description", "_description", "__doc__"):
         if hasattr(graph, attr):
             desc = getattr(graph, attr)
             if desc and isinstance(desc, str) and desc.strip():
                 return desc.strip()
     # Check if it's a compiled graph with a description in builder
-    if hasattr(graph, 'builder') and hasattr(graph.builder, 'description'):
+    if hasattr(graph, "builder") and hasattr(graph.builder, "description"):
         desc = graph.builder.description
         if desc and isinstance(desc, str) and desc.strip():
             return desc.strip()
@@ -283,59 +290,59 @@ def text_to_ascii_art(text: str) -> List[str]:
     """
     # Clean 3-line block font - each char is exactly 3 wide
     FONT = {
-        'A': ['▄▀▄', '█▀█', '▀ ▀'],
-        'B': ['█▀▄', '█▀▄', '▀▀▀'],
-        'C': ['▄▀▀', '█  ', '▀▀▀'],
-        'D': ['█▀▄', '█ █', '▀▀▀'],
-        'E': ['█▀▀', '█▀▀', '▀▀▀'],
-        'F': ['█▀▀', '█▀▀', '▀  '],
-        'G': ['▄▀▀', '█▀█', '▀▀▀'],
-        'H': ['█ █', '█▀█', '▀ ▀'],
-        'I': ['▀█▀', ' █ ', '▀▀▀'],
-        'J': ['▀▀█', '  █', '▀▀▀'],
-        'K': ['█ █', '█▀▄', '▀ ▀'],
-        'L': ['█  ', '█  ', '▀▀▀'],
-        'M': ['█▄█', '█ █', '▀ ▀'],
-        'N': ['█▀█', '█ █', '▀ ▀'],
-        'O': ['▄▀▄', '█ █', '▀▀▀'],
-        'P': ['█▀▄', '█▀▀', '▀  '],
-        'Q': ['▄▀▄', '█ █', '▀▀█'],
-        'R': ['█▀▄', '█▀▄', '▀ ▀'],
-        'S': ['▄▀▀', '▀▀▄', '▀▀▀'],
-        'T': ['▀█▀', ' █ ', ' ▀ '],
-        'U': ['█ █', '█ █', '▀▀▀'],
-        'V': ['█ █', '█ █', ' ▀ '],
-        'W': ['█ █', '█▀█', '▀ ▀'],
-        'X': ['▀▄▀', ' █ ', '▀ ▀'],
-        'Y': ['█ █', ' █ ', ' ▀ '],
-        'Z': ['▀▀█', ' █ ', '█▀▀'],
-        '0': ['▄▀▄', '█ █', '▀▀▀'],
-        '1': ['▄█ ', ' █ ', '▀▀▀'],
-        '2': ['▀▀█', '▄▀▀', '▀▀▀'],
-        '3': ['▀▀█', ' ▀█', '▀▀▀'],
-        '4': ['█ █', '▀▀█', '  ▀'],
-        '5': ['█▀▀', '▀▀▄', '▀▀▀'],
-        '6': ['▄▀▀', '█▀█', '▀▀▀'],
-        '7': ['▀▀█', '  █', '  ▀'],
-        '8': ['▄▀▄', '█▀█', '▀▀▀'],
-        '9': ['▄▀█', '▀▀█', '▀▀▀'],
-        ' ': ['   ', '   ', '   '],
-        '-': ['   ', '▀▀▀', '   '],
-        '_': ['   ', '   ', '▀▀▀'],
-        '.': ['   ', '   ', ' ▀ '],
+        "A": ["▄▀▄", "█▀█", "▀ ▀"],
+        "B": ["█▀▄", "█▀▄", "▀▀▀"],
+        "C": ["▄▀▀", "█  ", "▀▀▀"],
+        "D": ["█▀▄", "█ █", "▀▀▀"],
+        "E": ["█▀▀", "█▀▀", "▀▀▀"],
+        "F": ["█▀▀", "█▀▀", "▀  "],
+        "G": ["▄▀▀", "█▀█", "▀▀▀"],
+        "H": ["█ █", "█▀█", "▀ ▀"],
+        "I": ["▀█▀", " █ ", "▀▀▀"],
+        "J": ["▀▀█", "  █", "▀▀▀"],
+        "K": ["█ █", "█▀▄", "▀ ▀"],
+        "L": ["█  ", "█  ", "▀▀▀"],
+        "M": ["█▄█", "█ █", "▀ ▀"],
+        "N": ["█▀█", "█ █", "▀ ▀"],
+        "O": ["▄▀▄", "█ █", "▀▀▀"],
+        "P": ["█▀▄", "█▀▀", "▀  "],
+        "Q": ["▄▀▄", "█ █", "▀▀█"],
+        "R": ["█▀▄", "█▀▄", "▀ ▀"],
+        "S": ["▄▀▀", "▀▀▄", "▀▀▀"],
+        "T": ["▀█▀", " █ ", " ▀ "],
+        "U": ["█ █", "█ █", "▀▀▀"],
+        "V": ["█ █", "█ █", " ▀ "],
+        "W": ["█ █", "█▀█", "▀ ▀"],
+        "X": ["▀▄▀", " █ ", "▀ ▀"],
+        "Y": ["█ █", " █ ", " ▀ "],
+        "Z": ["▀▀█", " █ ", "█▀▀"],
+        "0": ["▄▀▄", "█ █", "▀▀▀"],
+        "1": ["▄█ ", " █ ", "▀▀▀"],
+        "2": ["▀▀█", "▄▀▀", "▀▀▀"],
+        "3": ["▀▀█", " ▀█", "▀▀▀"],
+        "4": ["█ █", "▀▀█", "  ▀"],
+        "5": ["█▀▀", "▀▀▄", "▀▀▀"],
+        "6": ["▄▀▀", "█▀█", "▀▀▀"],
+        "7": ["▀▀█", "  █", "  ▀"],
+        "8": ["▄▀▄", "█▀█", "▀▀▀"],
+        "9": ["▄▀█", "▀▀█", "▀▀▀"],
+        " ": ["   ", "   ", "   "],
+        "-": ["   ", "▀▀▀", "   "],
+        "_": ["   ", "   ", "▀▀▀"],
+        ".": ["   ", "   ", " ▀ "],
     }
 
     # Default char for unknown characters
-    DEFAULT = ['   ', ' █ ', '   ']
+    DEFAULT = ["   ", " █ ", "   "]
 
-    lines = ['', '', '']
+    lines = ["", "", ""]
     for char in text.upper():
         char_art = FONT.get(char, DEFAULT)
         for i in range(3):
-            lines[i] += char_art[i] + ' '
+            lines[i] += char_art[i] + " "
 
     # Remove only the final trailing space we added (not internal spaces from chars like T, P)
-    return [line[:-1] if line.endswith(' ') else line for line in lines]
+    return [line[:-1] if line.endswith(" ") else line for line in lines]
 
 
 def print_header_box(agent_name: str, cwd: str, description: Optional[str] = None):
@@ -359,7 +366,7 @@ def print_header_box(agent_name: str, cwd: str, description: Optional[str] = Non
     # Build cwd line with label
     cwd_label = "cwd: "
     max_cwd_len = inner_width - len(cwd_label)
-    cwd_display = cwd if len(cwd) <= max_cwd_len else "..." + cwd[-(max_cwd_len - 3):]
+    cwd_display = cwd if len(cwd) <= max_cwd_len else "..." + cwd[-(max_cwd_len - 3) :]
     cwd_with_label = f"{cwd_label}{cwd_display}"
     cwd_line = cwd_with_label.center(inner_width)
 
@@ -371,16 +378,24 @@ def print_header_box(agent_name: str, cwd: str, description: Optional[str] = Non
         # Print ASCII art lines centered
         for line in ascii_lines:
             centered_line = line.center(inner_width)
-            print(f"{BRIGHT_CYAN}{V}{RESET} {BOLD}{BRIGHT_CYAN}{centered_line}{RESET} {BRIGHT_CYAN}{V}{RESET}")
+            print(
+                f"{BRIGHT_CYAN}{V}{RESET} {BOLD}{BRIGHT_CYAN}{centered_line}{RESET} {BRIGHT_CYAN}{V}{RESET}"
+            )
     else:
         # Fall back to plain text if ASCII art doesn't fit
         title_line = agent_name.center(inner_width)
-        print(f"{BRIGHT_CYAN}{V}{RESET} {BOLD}{BRIGHT_CYAN}{title_line}{RESET} {BRIGHT_CYAN}{V}{RESET}")
+        print(
+            f"{BRIGHT_CYAN}{V}{RESET} {BOLD}{BRIGHT_CYAN}{title_line}{RESET} {BRIGHT_CYAN}{V}{RESET}"
+        )
 
     # Print description line if available
     if description:
         # Truncate description if too long
-        desc_display = description if len(description) <= inner_width else description[:inner_width - 3] + "..."
+        desc_display = (
+            description
+            if len(description) <= inner_width
+            else description[: inner_width - 3] + "..."
+        )
         desc_line = desc_display.center(inner_width)
         print(f"{CYAN}{V}{RESET} {DIM}{ITALIC}{desc_line}{RESET} {CYAN}{V}{RESET}")
 
@@ -417,17 +432,17 @@ def parse_agent_spec(agent_spec: str) -> Tuple[str, str]:
     Raises:
         ValueError: If format is invalid
     """
-    if ':' not in agent_spec:
+    if ":" not in agent_spec:
         raise ValueError(
             f"Invalid agent spec format: '{agent_spec}'. "
             f"Expected format: 'path/to/file.py:variable_name'"
         )
 
-    parts = agent_spec.rsplit(':', 1)
+    parts = agent_spec.rsplit(":", 1)
     file_path = parts[0]
     variable_name = parts[1]
 
-    if not file_path.endswith('.py'):
+    if not file_path.endswith(".py"):
         raise ValueError(f"Agent spec file must be a .py file: {file_path}")
 
     return file_path, variable_name
@@ -457,12 +472,12 @@ def load_graph(spec: str, default_graph_name: str = "graph"):
     """
     path_or_module = spec
     graph_name = default_graph_name
-    if ':' in spec:
-        head, _, tail = spec.rpartition(':')
+    if ":" in spec:
+        head, _, tail = spec.rpartition(":")
         # Only treat the trailing ':token' as a graph name if it looks like one
         # — i.e. it has no path separators. This avoids mistaking a Windows
         # drive-letter colon (e.g. 'C:\path\agent.py') for a name suffix.
-        if tail and '/' not in tail and '\\' not in tail:
+        if tail and "/" not in tail and "\\" not in tail:
             path_or_module = head
             graph_name = tail or default_graph_name
 
@@ -561,8 +576,8 @@ def print_chunk(chunk: Dict[str, Any], verbose: bool = False):
         print(f"\n{YELLOW}⚠ Action Required{RESET}")
         if action_requests:
             for i, action in enumerate(action_requests):
-                tool = action.get('tool', 'unknown')
-                args_preview = get_tool_arg_preview(action.get('args', {}))
+                tool = action.get("tool", "unknown")
+                args_preview = get_tool_arg_preview(action.get("args", {}))
                 print(f"  {DIM}{i + 1}. {tool}{RESET}")
                 if args_preview:
                     print(f"     {DIM}└─ {args_preview}{RESET}")
@@ -580,18 +595,18 @@ def get_key() -> str:
     if IS_WINDOWS:
         # Windows implementation using msvcrt
         ch = msvcrt.getch()
-        if ch in (b'\x00', b'\xe0'):  # Special keys (arrows, function keys)
+        if ch in (b"\x00", b"\xe0"):  # Special keys (arrows, function keys)
             ch2 = msvcrt.getch()
-            if ch2 == b'H':
-                return 'up'
-            elif ch2 == b'P':
-                return 'down'
-            return ch2.decode('utf-8', errors='ignore')
-        elif ch == b'\r':
-            return 'enter'
-        elif ch == b'\x03':  # Ctrl+C
-            return 'ctrl-c'
-        return ch.decode('utf-8', errors='ignore')
+            if ch2 == b"H":
+                return "up"
+            elif ch2 == b"P":
+                return "down"
+            return ch2.decode("utf-8", errors="ignore")
+        elif ch == b"\r":
+            return "enter"
+        elif ch == b"\x03":  # Ctrl+C
+            return "ctrl-c"
+        return ch.decode("utf-8", errors="ignore")
     else:
         # Unix implementation using termios/tty
         fd = sys.stdin.fileno()
@@ -600,18 +615,18 @@ def get_key() -> str:
             tty.setraw(fd)
             ch = sys.stdin.read(1)
             # Handle escape sequences (arrow keys)
-            if ch == '\x1b':
+            if ch == "\x1b":
                 ch2 = sys.stdin.read(1)
-                if ch2 == '[':
+                if ch2 == "[":
                     ch3 = sys.stdin.read(1)
-                    if ch3 == 'A':
-                        return 'up'
-                    elif ch3 == 'B':
-                        return 'down'
-            elif ch == '\r' or ch == '\n':
-                return 'enter'
-            elif ch == '\x03':  # Ctrl+C
-                return 'ctrl-c'
+                    if ch3 == "A":
+                        return "up"
+                    elif ch3 == "B":
+                        return "down"
+            elif ch == "\r" or ch == "\n":
+                return "enter"
+            elif ch == "\x03":  # Ctrl+C
+                return "ctrl-c"
             return ch
         finally:
             termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
@@ -647,13 +662,13 @@ def select_option(options: List[str], prompt: str = "Select an option:") -> int:
         while True:
             key = get_key()
 
-            if key == 'up' and selected > 0:
+            if key == "up" and selected > 0:
                 selected -= 1
-            elif key == 'down' and selected < num_options - 1:
+            elif key == "down" and selected < num_options - 1:
                 selected += 1
-            elif key == 'enter':
+            elif key == "enter":
                 break
-            elif key == 'ctrl-c':
+            elif key == "ctrl-c":
                 print("\033[?25h", end="")  # Show cursor
                 sys.exit(0)
 
@@ -732,7 +747,9 @@ async def run_single_turn_async(
         spinner = Spinner("Thinking")
         spinner.start()
 
-        async for chunk in astream_graph_updates(graph, input_data, config=config, stream_mode=stream_mode):
+        async for chunk in astream_graph_updates(
+            graph, input_data, config=config, stream_mode=stream_mode
+        ):
             # Stop spinner on first chunk
             if first_chunk:
                 spinner.stop()
@@ -779,7 +796,9 @@ def run_single_turn_sync(
         spinner = Spinner("Thinking")
         spinner.start()
 
-        for chunk in stream_graph_updates(graph, input_data, config=config, stream_mode=stream_mode):
+        for chunk in stream_graph_updates(
+            graph, input_data, config=config, stream_mode=stream_mode
+        ):
             # Stop spinner on first chunk
             if first_chunk:
                 spinner.stop()
@@ -832,6 +851,7 @@ def print_help():
 
 # --- Built-in Slash Commands ---
 
+
 @register_command(
     name="help",
     description="Show this help message",
@@ -943,6 +963,7 @@ def cmd_config(args: str, context: Dict[str, Any]) -> Optional[str]:
         # Full resolved view: each value, where it came from, and the env var
         # / TOML key that sets it.
         from deepagent_code.config import CodeConfig
+
         for line in CodeConfig.resolve().describe().splitlines():
             print(f"  {line}")
 
@@ -1178,10 +1199,14 @@ def run_conversation_loop(
 
         if use_async:
             duration = asyncio.run(
-                run_single_turn_async(graph, initial_message, config, interactive, verbose, stream_mode)
+                run_single_turn_async(
+                    graph, initial_message, config, interactive, verbose, stream_mode
+                )
             )
         else:
-            duration = run_single_turn_sync(graph, initial_message, config, interactive, verbose, stream_mode)
+            duration = run_single_turn_sync(
+                graph, initial_message, config, interactive, verbose, stream_mode
+            )
         print_timing(duration, verbose)
         print()
 
@@ -1252,10 +1277,14 @@ def run_conversation_loop(
             # Run the agent
             if use_async:
                 duration = asyncio.run(
-                    run_single_turn_async(graph, user_input, config, interactive, verbose, stream_mode)
+                    run_single_turn_async(
+                        graph, user_input, config, interactive, verbose, stream_mode
+                    )
                 )
             else:
-                duration = run_single_turn_sync(graph, user_input, config, interactive, verbose, stream_mode)
+                duration = run_single_turn_sync(
+                    graph, user_input, config, interactive, verbose, stream_mode
+                )
             print_timing(duration, verbose)
             print()
 
@@ -1310,6 +1339,19 @@ def run_conversation_loop(
     default=None,
     help="Show verbose output including node names",
 )
+@click.option(
+    "--demo",
+    is_flag=True,
+    default=False,
+    help="Run with the built-in keyless demo agent — no API key needed",
+)
+@click.option(
+    "--show-config",
+    "show_config",
+    is_flag=True,
+    default=False,
+    help="Print the resolved configuration (defaults < deepagents.toml < env < CLI) and exit",
+)
 def main(
     message: Optional[str],
     agent_spec: Optional[str],
@@ -1319,6 +1361,8 @@ def main(
     use_async: Optional[bool],
     stream_mode: Optional[str],
     verbose: Optional[bool],
+    demo: bool,
+    show_config: bool,
 ):
     """
     Run a LangGraph agent from the command line.
@@ -1350,7 +1394,20 @@ def main(
         deepagent-code -a my_agent.py "What can you do?"
         deepagent-code -a my_agent.py:graph
         deepagent-code -f ./prompt.md
+        deepagent-code --demo "try it with no API key"
+        deepagent-code --show-config
     """
+    if show_config:
+        print(config_module.CodeConfig.resolve(toml_start=Path.cwd()).describe())
+        return
+
+    if demo:
+        if agent_spec:
+            print(f"{RED}⏺ Error: --demo and -a/--agent are mutually exclusive{RESET}")
+            sys.exit(1)
+        # The keyless echo agent shipped with the shared core.
+        agent_spec = "langgraph_stream_parser.demo.stub:graph"
+
     try:
         # Handle -f/--file option: read message from file
         if prompt_file and message:
@@ -1359,7 +1416,7 @@ def main(
 
         if prompt_file:
             try:
-                with open(prompt_file, 'r', encoding='utf-8') as f:
+                with open(prompt_file, "r", encoding="utf-8") as f:
                     message = f.read().strip()
                 if not message:
                     print(f"{RED}⏺ Error: File '{prompt_file}' is empty{RESET}")
@@ -1397,9 +1454,7 @@ def main(
         verbose = cfg.verbose
         # Only change directory when a workspace root was actually configured.
         workspace_root = (
-            cfg.workspace_root
-            if cfg.sources.get("workspace_root") != "default"
-            else None
+            cfg.workspace_root if cfg.sources.get("workspace_root") != "default" else None
         )
 
         # If no spec provided, try the default agent
@@ -1410,8 +1465,8 @@ def main(
             else:
                 print(f"{RED}⏺ Error: No agent specified.{RESET}")
                 print(f"\n{DIM}Usage:{RESET}")
-                print(f"  deepagent-code path/to/agent.py:graph")
-                print(f"  deepagent-code mypackage.module:agent")
+                print("  deepagent-code path/to/agent.py:graph")
+                print("  deepagent-code mypackage.module:agent")
                 print(f"\n{DIM}Or set DEEPAGENT_AGENT_SPEC environment variable{RESET}")
                 sys.exit(1)
 
@@ -1472,6 +1527,7 @@ def main(
         print(f"{RED}⏺ Error: {e}{RESET}")
         if verbose:
             import traceback
+
             print(traceback.format_exc())
         sys.exit(1)
 

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/deepagent_code/config.py

@@ -9,6 +9,7 @@ vars, then CLI overrides.
 ``get`` / ``resolve`` remain for the ``[configurable]`` passthrough and ad-hoc
 lookups.
 """
+
 import os
 import tomllib
 import warnings

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/deepagent_code.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepagent-code
-Version: 0.2.0
+Version: 0.3.0
 Summary: A Claude Code-style CLI for running LangGraph agents from the terminal
 Author-email: Kedar Dabhadkar <kdabhadk@gmail.com>
 License-Expression: MIT
@@ -19,7 +19,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: langgraph>=0.2.0
-Requires-Dist: langgraph-stream-parser<0.3,>=0.2
+Requires-Dist: langgraph-stream-parser<0.3,>=0.2.2
 Requires-Dist: click>=8.0.0
 Requires-Dist: python-dotenv
 Requires-Dist: deepagents
@@ -27,7 +27,7 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
 Requires-Dist: black>=23.0.0; extra == "dev"
-Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: ruff==0.15.15; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Dynamic: license-file
 
@@ -37,6 +37,19 @@ A Claude Code-style CLI for running LangGraph agents from the terminal.
 
 ![deepagent-code](examples/image.png)
 
+## One agent, every surface
+
+deepagent-code is the terminal surface of the **deep-agent family**: write your agent once — any LangGraph `CompiledGraph` — and run it on every surface with the same spec string (`module:attr` or `path/to/file.py:attr`), the same `deepagents.toml` config file, and the same `DEEPAGENT_*` environment variables.
+
+| Surface | Package | Try it |
+|---|---|---|
+| Web app | [cowork-dash](https://github.com/dkedar7/cowork-dash) | `cowork-dash run --agent my_agent.py:graph` |
+| JupyterLab | [deepagent-lab](https://github.com/dkedar7/deepagent-lab) | `pip install deepagent-lab`, then the chat sidebar in `jupyter lab` |
+| Terminal | deepagent-code | **you are here** |
+| VS Code | [deepagent-vscode](https://github.com/dkedar7/deepagent-vscode) | chat participant + stdio sidecar |
+| Reference agent | [deepagent-hermes](https://github.com/dkedar7/deepagent-hermes) | `DEEPAGENT_AGENT_SPEC=deepagent_hermes.agent:graph` on any surface |
+| Shared core | [langgraph-stream-parser](https://github.com/dkedar7/langgraph-stream-parser) | typed events + config resolver behind every surface |
+
 ## Installation
 
 ```bash
@@ -50,6 +63,11 @@ pip install git+https://github.com/dkedar7/deepagent-code.git
 
 ## Quick Start
 
+No agent or API key yet? See the CLI working in one command:
+```bash
+deepagent-code --demo "hello"
+```
+
 Run with the default agent (requires `ANTHROPIC_API_KEY`):
 ```bash
 export ANTHROPIC_API_KEY="your_api_key"
@@ -86,6 +104,13 @@ deepagent-code --no-interactive
 
 # Verbose output
 deepagent-code -v
+
+# Keyless demo agent (no API key needed)
+deepagent-code --demo
+
+# Print the resolved configuration: each value, its source, and the
+# env var / deepagents.toml key that sets it
+deepagent-code --show-config
 ```
 
 ## Commands
@@ -99,7 +124,8 @@ In the interactive loop:
 
 ```bash
 # Agent location (path/to/file.py:variable_name or module:variable)
-export DEEPAGENT_SPEC="my_agent.py:graph"
+# (DEEPAGENT_SPEC is still accepted as a deprecated alias)
+export DEEPAGENT_AGENT_SPEC="my_agent.py:graph"
 deepagent-code
 
 # Working directory

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/deepagent_code.egg-info/requires.txt

@@ -1,5 +1,5 @@
 langgraph>=0.2.0
-langgraph-stream-parser<0.3,>=0.2
+langgraph-stream-parser<0.3,>=0.2.2
 click>=8.0.0
 python-dotenv
 deepagents
@@ -8,5 +8,5 @@ deepagents
 pytest>=7.0.0
 pytest-asyncio>=0.21.0
 black>=23.0.0
-ruff>=0.1.0
+ruff==0.15.15
 mypy>=1.0.0

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "deepagent-code"
-version = "0.2.0"
+version = "0.3.0"
 description = "A Claude Code-style CLI for running LangGraph agents from the terminal"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,7 +25,7 @@ classifiers = [
 
 dependencies = [
     "langgraph>=0.2.0",
-    "langgraph-stream-parser>=0.2,<0.3",
+    "langgraph-stream-parser>=0.2.2,<0.3",
     "click>=8.0.0",
     "python-dotenv",
     "deepagents",
@@ -36,7 +36,7 @@ dev = [
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
     "black>=23.0.0",
-    "ruff>=0.1.0",
+    "ruff==0.15.15",
     "mypy>=1.0.0",
 ]
 
@@ -60,6 +60,10 @@ target-version = ['py313']
 line-length = 100
 target-version = "py313"
 
+[tool.ruff.lint.per-file-ignores]
+# Example scripts call load_dotenv() before importing modules that read env.
+"examples/*" = ["E402"]
+
 [tool.mypy]
 python_version = "3.13"
 warn_return_any = true

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/tests/test_cli.py

@@ -1,6 +1,32 @@
 """Tests for CLI functions."""
+
 import pytest
-from deepagent_code.cli import parse_agent_spec
+from click.testing import CliRunner
+
+from deepagent_code.cli import main, parse_agent_spec
+
+
+class TestCliFlags:
+    """Tests for --show-config and --demo."""
+
+    def test_show_config_prints_resolved_config(self):
+        result = CliRunner().invoke(main, ["--show-config"])
+        assert result.exit_code == 0, result.output
+        assert "DEEPAGENT_AGENT_SPEC" in result.output
+
+    def test_demo_and_agent_are_mutually_exclusive(self):
+        result = CliRunner().invoke(main, ["--demo", "-a", "x.py:g", "hi"])
+        assert result.exit_code != 0
+        assert "mutually exclusive" in result.output
+
+    def test_demo_replies_without_any_key(self, monkeypatch):
+        # A full one-shot turn through the real stub agent — proves --demo
+        # works on a machine with no API keys configured.
+        monkeypatch.delenv("ANTHROPIC_API_KEY", raising=False)
+        monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+        result = CliRunner().invoke(main, ["--demo", "--no-interactive", "hello demo"])
+        assert result.exit_code == 0, result.output
+        assert "hello demo" in result.output
 
 
 class TestParseAgentSpec:

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/tests/test_codeconfig.py

@@ -1,4 +1,5 @@
 """Tests for CodeConfig — deepagent-code's HostConfig subclass."""
+
 from pathlib import Path
 
 import pytest
@@ -34,9 +35,11 @@ def test_env_stream_mode(isolated, tmp_path):
 
 
 def test_toml_keys(isolated, tmp_path):
-    _toml(tmp_path,
-          '[agent]\nspec = "a.py:g"\ngraph_name = "myg"\n'
-          '[ui]\nverbose = true\nasync_mode = true\nstream_mode = "values"\n')
+    _toml(
+        tmp_path,
+        '[agent]\nspec = "a.py:g"\ngraph_name = "myg"\n'
+        '[ui]\nverbose = true\nasync_mode = true\nstream_mode = "values"\n',
+    )
     cfg = CodeConfig.resolve(env={}, toml_start=tmp_path)
     assert cfg.agent_spec == "a.py:g"
     assert cfg.graph_name == "myg"

{deepagent_code-0.2.0 → deepagent_code-0.3.0}/tests/test_config.py

@@ -1,4 +1,5 @@
 """Tests for deepagent_code.config."""
+
 from __future__ import annotations
 
 from pathlib import Path
@@ -23,7 +24,7 @@ def test_returns_empty_when_no_files(tmp_path, monkeypatch):
 
 def test_loads_global_only(tmp_path, monkeypatch):
     home = tmp_path / "home"
-    _write(home / "config.toml", '[ui]\nverbose = true\n')
+    _write(home / "config.toml", "[ui]\nverbose = true\n")
     monkeypatch.setenv("DEEPAGENTS_CONFIG_HOME", str(home))
     monkeypatch.chdir(tmp_path)
     cfg, sources = config.load_config()
@@ -47,7 +48,7 @@ def test_project_overrides_global(tmp_path, monkeypatch):
     monkeypatch.setenv("DEEPAGENTS_CONFIG_HOME", str(home))
 
     project = tmp_path / "proj"
-    _write(project / "deepagents.toml", '[ui]\nverbose = true\n')
+    _write(project / "deepagents.toml", "[ui]\nverbose = true\n")
     monkeypatch.chdir(project)
 
     cfg, sources = config.load_config()
@@ -61,7 +62,7 @@ def test_walks_up_for_project_config(tmp_path, monkeypatch):
     project = tmp_path / "proj"
     nested = project / "a" / "b" / "c"
     nested.mkdir(parents=True)
-    _write(project / "deepagents.toml", '[ui]\nverbose = true\n')
+    _write(project / "deepagents.toml", "[ui]\nverbose = true\n")
     monkeypatch.chdir(nested)
 
     cfg, sources = config.load_config()
@@ -99,9 +100,9 @@ def test_resolve_precedence(monkeypatch):
     monkeypatch.setenv("UI_VERBOSE", "false")
     assert config.resolve(cfg, "ui.verbose", env_var="UI_VERBOSE", cast=bool) is False
     # cli beats env
-    assert config.resolve(
-        cfg, "ui.verbose", cli_value=True, env_var="UI_VERBOSE", cast=bool
-    ) is True
+    assert (
+        config.resolve(cfg, "ui.verbose", cli_value=True, env_var="UI_VERBOSE", cast=bool) is True
+    )
 
 
 def test_resolve_bool_cast(monkeypatch):