agentic-cli 0.2.0__tar.gz → 0.3.1__tar.gz

{agentic_cli-0.2.0 → agentic_cli-0.3.1}/CHANGELOG.md

@@ -5,6 +5,64 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-01-28
+
+### Added
+
+- **Task Progress Display**: Thinking box now shows dynamic task progress with status icons (◐ ☐ ✓ ✗)
+- `TASK_PROGRESS` event type for signaling task graph updates
+- `TaskGraph.to_compact_display()` for condensed status display
+
+### Changed
+
+- **Background Initialization**: Workflow manager now initializes services in background, eliminating first-message lag
+- Simplified LangGraph imports - removed `_import_langgraph` helper in favor of direct imports
+
+## [0.3.0] - 2025-01-27
+
+### Added
+
+- **Memory System** with 3-tier architecture:
+  - `WorkingMemory` - Session-scoped context with tags and serialization
+  - `LongTermMemory` - Persistent memory with knowledge base references
+  - `MemoryManager` - Unified interface for working and long-term memory
+  - Memory tools (`working_memory_tool`, `long_term_memory_tool`)
+- **Planning System**:
+  - `TaskGraph` - Work plan management with dependencies and status tracking
+  - `TaskStatus` enum for pending/in_progress/completed/blocked states
+  - `Task` dataclass with subtasks, dependencies, and metadata
+- **Human-in-the-Loop (HITL) System**:
+  - `ApprovalManager` - Configurable approval gates with auto-approve patterns
+  - `CheckpointManager` - Review checkpoints with continue/edit/regenerate/abort actions
+  - `HITLConfig` and `ApprovalRule` for configuration
+- **New Tools**:
+  - `shell_executor` with safety controls (blocks dangerous commands)
+  - `file_manager` with read/write/list/copy/move/delete operations
+  - `diff_compare` with unified/side-by-side/summary modes
+- New tool categories: `MEMORY`, `PLANNING`, `SYSTEM`
+- Framework-provided tools with auto-detection
+- Layered JSON settings persistence with organized mixins
+- `research_demo` example showcasing memory, planning, and file operations
+
+### Changed
+
+- **LangGraph Module Reorganization**:
+  - Moved to dedicated `workflow/langgraph/` submodule
+  - Added `persistence/` for checkpointers and stores
+  - Added `tools/` for shell and file search utilities
+- **Simplified LangGraphWorkflowManager**:
+  - Removed dead middleware module (~400 lines)
+  - Use explicit provider instantiation (GenAI for Gemini, not VertexAI)
+  - Simplified model creation with thinking support for Claude and Gemini
+- **BaseCLIApp Simplification**:
+  - Constructor-based configuration instead of method overrides
+  - `AppInfo` is now a constructor parameter
+
+### Fixed
+
+- LangGraph no longer requires `langchain-google-vertexai` package
+- Explicit provider detection prevents VertexAI initialization errors
+
 ## [0.2.0] - 2025-01-25
 
 ### Added

{agentic_cli-0.2.0 → agentic_cli-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentic-cli
-Version: 0.2.0
+Version: 0.3.1
 Summary: A framework for building domain-specific agentic CLI applications
 Project-URL: Homepage, https://github.com/shoom1/agentic-cli
 Project-URL: Repository, https://github.com/shoom1/agentic-cli
@@ -60,6 +60,8 @@ Agentic CLI provides the core infrastructure for building interactive CLI applic
 │  - Terminal UI (thinking-prompt)                                    │
 │  - Command registry (/help, /status, /clear, etc.)                  │
 │  - Message history                                                  │
+│  - Background initialization (no first-message lag)                 │
+│  - Task progress display in thinking box                            │
 └─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
@@ -120,8 +122,9 @@ Create a minimal CLI application in just a few lines:
 
 ```python
 import asyncio
-from agentic_cli import BaseCLIApp, BaseSettings, AgentConfig, GoogleADKWorkflowManager
+from agentic_cli import BaseCLIApp, BaseSettings
 from agentic_cli.cli import AppInfo
+from agentic_cli.workflow import AgentConfig
 
 # Define your tools
 def greet(name: str) -> dict:
@@ -137,19 +140,14 @@ AGENTS = [
     ),
 ]
 
-# Create your app
-class MyApp(BaseCLIApp):
-    def get_app_info(self) -> AppInfo:
-        return AppInfo(name="My App", version="0.1.0")
-
-    def get_settings(self) -> BaseSettings:
-        return BaseSettings()
-
-    def create_workflow_manager(self) -> GoogleADKWorkflowManager:
-        return GoogleADKWorkflowManager(agent_configs=AGENTS, settings=self._settings)
-
+# Create and run your app
 if __name__ == "__main__":
-    asyncio.run(MyApp().run())
+    app = BaseCLIApp(
+        app_info=AppInfo(name="My App", version="0.1.0"),
+        agent_configs=AGENTS,
+        settings=BaseSettings(),
+    )
+    asyncio.run(app.run())
 ```
 
 Run with your API key:
@@ -182,20 +180,26 @@ manager = GoogleADKWorkflowManager(
 
 Uses LangGraph for orchestration. Best for:
 - Cyclical workflows (self-validation, iterative refinement)
-- Model-agnostic operation (OpenAI, Anthropic, Google)
+- Model-agnostic operation (OpenAI, Anthropic, Google via GenAI)
 - State checkpointing and time-travel debugging
 - Complex multi-agent coordination
 
 ```python
-from agentic_cli import LangGraphWorkflowManager
+from agentic_cli.workflow.langgraph import LangGraphWorkflowManager
 
 manager = LangGraphWorkflowManager(
     agent_configs=AGENTS,
     settings=settings,
-    checkpointer="memory",  # or "postgres" for persistence
+    checkpointer="memory",  # "memory", "postgres", "sqlite", or None
 )
 ```
 
+Features:
+- **Explicit provider support**: Uses `langchain-google-genai` for Gemini (not VertexAI)
+- **Thinking mode**: Native support for Claude and Gemini thinking/reasoning
+- **Retry policies**: Automatic retry with exponential backoff
+- **Event streaming**: Real-time workflow events via `WorkflowEvent`
+
 Requires: `pip install agentic-cli[langgraph]`
 
 ### Comparison
@@ -204,9 +208,10 @@ Requires: `pip install agentic-cli[langgraph]`
 |---------|------------|-----------|
 | Setup complexity | Simple | Moderate |
 | Cyclical workflows | Limited | Native |
-| Multi-provider | Google only | OpenAI, Anthropic, Google |
-| State persistence | In-memory | Memory or PostgreSQL |
-| Thinking support | Native (Gemini) | Via model config |
+| Multi-provider | Google only | OpenAI, Anthropic, Google (GenAI) |
+| State persistence | In-memory | Memory, PostgreSQL, or SQLite |
+| Thinking support | Native (Gemini) | Native (Claude & Gemini) |
+| Retry handling | Manual | Built-in with backoff |
 
 ### Auto-selection via Settings
 
@@ -427,6 +432,7 @@ WorkflowEvent types for UI integration:
 | `CODE_EXECUTION` | Code execution result | outcome |
 | `ERROR` | Error message | recoverable, error_code |
 | `USER_INPUT_REQUIRED` | Tool needs user input | request_id, prompt |
+| `TASK_PROGRESS` | Task graph update | current_task_description, progress |
 
 ### Processing Events
 
@@ -442,12 +448,31 @@ async for event in manager.process(message, user_id="user1"):
         print(f"Result: {event.metadata['result']}")
 ```
 
+### Task Progress Display
+
+When using a task graph for planning, the CLI thinking box dynamically shows task progress:
+
+```
+Calling: search_web
+─── Tasks: 2/5 ───
+◐ Researching topic
+☐ Analyzing results
+☐ Writing summary
+```
+
+Status icons:
+- `◐` In progress
+- `☐` Pending
+- `✓` Completed
+- `✗` Failed
+
 ## Examples
 
 See the `examples/` directory for complete working examples:
 
 - **hello_agent.py** - Simple assistant using Google ADK
-- **hello_langgraph.py** - Same assistant using LangGraph
+- **hello_langgraph.py** - Same assistant using LangGraph orchestration
+- **research_demo/** - Full-featured research assistant with memory, planning, and file operations
 
 Run examples:
 
@@ -458,6 +483,9 @@ python examples/hello_agent.py
 # Or with LangGraph (requires langgraph extra)
 pip install agentic-cli[langgraph]
 python examples/hello_langgraph.py
+
+# Research demo (full features)
+python -m examples.research_demo
 ```
 
 ## Development
@@ -489,14 +517,19 @@ agentic-cli/
 │   │   ├── events.py         # WorkflowEvent, EventType
 │   │   ├── config.py         # AgentConfig
 │   │   ├── adk_manager.py    # GoogleADKWorkflowManager
-│   │   └── langgraph_manager.py  # LangGraphWorkflowManager
+│   │   └── langgraph/        # LangGraph submodule
+│   │       ├── manager.py    # LangGraphWorkflowManager
+│   │       ├── state.py      # AgentState, CheckpointData
+│   │       ├── persistence/  # Checkpointers and stores
+│   │       └── tools/        # Shell, file search tools
 │   ├── tools/
 │   │   └── executor.py       # SafePythonExecutor
 │   └── knowledge_base/
 │       └── manager.py        # KnowledgeBaseManager
 ├── examples/
 │   ├── hello_agent.py
-│   └── hello_langgraph.py
+│   ├── hello_langgraph.py
+│   └── research_demo/        # Full-featured example
 └── tests/
 ```
 

{agentic_cli-0.2.0 → agentic_cli-0.3.1}/README.md

@@ -21,6 +21,8 @@ Agentic CLI provides the core infrastructure for building interactive CLI applic
 │  - Terminal UI (thinking-prompt)                                    │
 │  - Command registry (/help, /status, /clear, etc.)                  │
 │  - Message history                                                  │
+│  - Background initialization (no first-message lag)                 │
+│  - Task progress display in thinking box                            │
 └─────────────────────────────────────────────────────────────────────┘
                                  │
                                  ▼
@@ -81,8 +83,9 @@ Create a minimal CLI application in just a few lines:
 
 ```python
 import asyncio
-from agentic_cli import BaseCLIApp, BaseSettings, AgentConfig, GoogleADKWorkflowManager
+from agentic_cli import BaseCLIApp, BaseSettings
 from agentic_cli.cli import AppInfo
+from agentic_cli.workflow import AgentConfig
 
 # Define your tools
 def greet(name: str) -> dict:
@@ -98,19 +101,14 @@ AGENTS = [
     ),
 ]
 
-# Create your app
-class MyApp(BaseCLIApp):
-    def get_app_info(self) -> AppInfo:
-        return AppInfo(name="My App", version="0.1.0")
-
-    def get_settings(self) -> BaseSettings:
-        return BaseSettings()
-
-    def create_workflow_manager(self) -> GoogleADKWorkflowManager:
-        return GoogleADKWorkflowManager(agent_configs=AGENTS, settings=self._settings)
-
+# Create and run your app
 if __name__ == "__main__":
-    asyncio.run(MyApp().run())
+    app = BaseCLIApp(
+        app_info=AppInfo(name="My App", version="0.1.0"),
+        agent_configs=AGENTS,
+        settings=BaseSettings(),
+    )
+    asyncio.run(app.run())
 ```
 
 Run with your API key:
@@ -143,20 +141,26 @@ manager = GoogleADKWorkflowManager(
 
 Uses LangGraph for orchestration. Best for:
 - Cyclical workflows (self-validation, iterative refinement)
-- Model-agnostic operation (OpenAI, Anthropic, Google)
+- Model-agnostic operation (OpenAI, Anthropic, Google via GenAI)
 - State checkpointing and time-travel debugging
 - Complex multi-agent coordination
 
 ```python
-from agentic_cli import LangGraphWorkflowManager
+from agentic_cli.workflow.langgraph import LangGraphWorkflowManager
 
 manager = LangGraphWorkflowManager(
     agent_configs=AGENTS,
     settings=settings,
-    checkpointer="memory",  # or "postgres" for persistence
+    checkpointer="memory",  # "memory", "postgres", "sqlite", or None
 )
 ```
 
+Features:
+- **Explicit provider support**: Uses `langchain-google-genai` for Gemini (not VertexAI)
+- **Thinking mode**: Native support for Claude and Gemini thinking/reasoning
+- **Retry policies**: Automatic retry with exponential backoff
+- **Event streaming**: Real-time workflow events via `WorkflowEvent`
+
 Requires: `pip install agentic-cli[langgraph]`
 
 ### Comparison
@@ -165,9 +169,10 @@ Requires: `pip install agentic-cli[langgraph]`
 |---------|------------|-----------|
 | Setup complexity | Simple | Moderate |
 | Cyclical workflows | Limited | Native |
-| Multi-provider | Google only | OpenAI, Anthropic, Google |
-| State persistence | In-memory | Memory or PostgreSQL |
-| Thinking support | Native (Gemini) | Via model config |
+| Multi-provider | Google only | OpenAI, Anthropic, Google (GenAI) |
+| State persistence | In-memory | Memory, PostgreSQL, or SQLite |
+| Thinking support | Native (Gemini) | Native (Claude & Gemini) |
+| Retry handling | Manual | Built-in with backoff |
 
 ### Auto-selection via Settings
 
@@ -388,6 +393,7 @@ WorkflowEvent types for UI integration:
 | `CODE_EXECUTION` | Code execution result | outcome |
 | `ERROR` | Error message | recoverable, error_code |
 | `USER_INPUT_REQUIRED` | Tool needs user input | request_id, prompt |
+| `TASK_PROGRESS` | Task graph update | current_task_description, progress |
 
 ### Processing Events
 
@@ -403,12 +409,31 @@ async for event in manager.process(message, user_id="user1"):
         print(f"Result: {event.metadata['result']}")
 ```
 
+### Task Progress Display
+
+When using a task graph for planning, the CLI thinking box dynamically shows task progress:
+
+```
+Calling: search_web
+─── Tasks: 2/5 ───
+◐ Researching topic
+☐ Analyzing results
+☐ Writing summary
+```
+
+Status icons:
+- `◐` In progress
+- `☐` Pending
+- `✓` Completed
+- `✗` Failed
+
 ## Examples
 
 See the `examples/` directory for complete working examples:
 
 - **hello_agent.py** - Simple assistant using Google ADK
-- **hello_langgraph.py** - Same assistant using LangGraph
+- **hello_langgraph.py** - Same assistant using LangGraph orchestration
+- **research_demo/** - Full-featured research assistant with memory, planning, and file operations
 
 Run examples:
 
@@ -419,6 +444,9 @@ python examples/hello_agent.py
 # Or with LangGraph (requires langgraph extra)
 pip install agentic-cli[langgraph]
 python examples/hello_langgraph.py
+
+# Research demo (full features)
+python -m examples.research_demo
 ```
 
 ## Development
@@ -450,14 +478,19 @@ agentic-cli/
 │   │   ├── events.py         # WorkflowEvent, EventType
 │   │   ├── config.py         # AgentConfig
 │   │   ├── adk_manager.py    # GoogleADKWorkflowManager
-│   │   └── langgraph_manager.py  # LangGraphWorkflowManager
+│   │   └── langgraph/        # LangGraph submodule
+│   │       ├── manager.py    # LangGraphWorkflowManager
+│   │       ├── state.py      # AgentState, CheckpointData
+│   │       ├── persistence/  # Checkpointers and stores
+│   │       └── tools/        # Shell, file search tools
 │   ├── tools/
 │   │   └── executor.py       # SafePythonExecutor
 │   └── knowledge_base/
 │       └── manager.py        # KnowledgeBaseManager
 ├── examples/
 │   ├── hello_agent.py
-│   └── hello_langgraph.py
+│   ├── hello_langgraph.py
+│   └── research_demo/        # Full-featured example
 └── tests/
 ```
 

{agentic_cli-0.2.0 → agentic_cli-0.3.1}/examples/hello_agent.py

@@ -15,8 +15,7 @@ from pydantic_settings import SettingsConfigDict
 
 from agentic_cli import BaseCLIApp, BaseSettings
 from agentic_cli.cli import AppInfo
-from agentic_cli.config import set_settings
-from agentic_cli.workflow import AgentConfig, GoogleADKWorkflowManager
+from agentic_cli.workflow import AgentConfig
 
 
 # =============================================================================
@@ -83,26 +82,24 @@ AGENT_CONFIGS = [
 ]
 
 
-class HelloAgentApp(BaseCLIApp):
-    def get_app_info(self) -> AppInfo:
-        text = Text()
-        text.append("Hello Agent\n\n", style="bold cyan")
-        text.append("Tools: get_current_time, calculate, echo\n", style="dim")
-        text.append("Type /help for commands", style="dim")
-        return AppInfo(
-            name="Hello Agent",
-            version="0.1.0",
-            welcome_message=lambda: Panel(text, border_style="cyan"),
-            echo_thinking=False,
-        )
-
-    def get_settings(self) -> Settings:
-        return get_settings()
-
-    def create_workflow_manager(self) -> GoogleADKWorkflowManager:
-        set_settings(self._settings)
-        return GoogleADKWorkflowManager(agent_configs=AGENT_CONFIGS, settings=self._settings)
+def _create_app_info() -> AppInfo:
+    """Create the application info for the welcome message."""
+    text = Text()
+    text.append("Hello Agent\n\n", style="bold cyan")
+    text.append("Tools: get_current_time, calculate, echo\n", style="dim")
+    text.append("Type /help for commands", style="dim")
+    return AppInfo(
+        name="Hello Agent",
+        version="0.1.0",
+        welcome_message=lambda: Panel(text, border_style="cyan"),
+        echo_thinking=False,
+    )
 
 
 if __name__ == "__main__":
-    asyncio.run(HelloAgentApp().run())
+    app = BaseCLIApp(
+        app_info=_create_app_info(),
+        agent_configs=AGENT_CONFIGS,
+        settings=get_settings(),
+    )
+    asyncio.run(app.run())

{agentic_cli-0.2.0 → agentic_cli-0.3.1}/examples/hello_langgraph.py

@@ -22,9 +22,7 @@ from pydantic_settings import SettingsConfigDict
 
 from agentic_cli import BaseCLIApp, BaseSettings
 from agentic_cli.cli import AppInfo
-from agentic_cli.config import set_settings
 from agentic_cli.workflow import AgentConfig
-from agentic_cli.workflow.langgraph_manager import LangGraphWorkflowManager
 
 
 # =============================================================================
@@ -100,33 +98,25 @@ AGENT_CONFIGS = [
 # Application
 # =============================================================================
 
-class HelloLangGraphApp(BaseCLIApp):
-    """Example CLI app using LangGraph for orchestration."""
-
-    def get_app_info(self) -> AppInfo:
-        text = Text()
-        text.append("Hello LangGraph\n\n", style="bold magenta")
-        text.append("Orchestrator: LangGraph\n", style="dim")
-        text.append("Tools: get_current_time, calculate, echo\n", style="dim")
-        text.append("Type /help for commands", style="dim")
-        return AppInfo(
-            name="Hello LangGraph",
-            version="0.1.0",
-            welcome_message=lambda: Panel(text, border_style="magenta"),
-            echo_thinking=False,
-        )
-
-    def get_settings(self) -> Settings:
-        return get_settings()
-
-    def create_workflow_manager(self) -> LangGraphWorkflowManager:
-        set_settings(self._settings)
-        return LangGraphWorkflowManager(
-            agent_configs=AGENT_CONFIGS,
-            settings=self._settings,
-            checkpointer="memory",  # Use in-memory checkpointing
-        )
+def _create_app_info() -> AppInfo:
+    """Create the application info for the welcome message."""
+    text = Text()
+    text.append("Hello LangGraph\n\n", style="bold magenta")
+    text.append("Orchestrator: LangGraph\n", style="dim")
+    text.append("Tools: get_current_time, calculate, echo\n", style="dim")
+    text.append("Type /help for commands", style="dim")
+    return AppInfo(
+        name="Hello LangGraph",
+        version="0.1.0",
+        welcome_message=lambda: Panel(text, border_style="magenta"),
+        echo_thinking=False,
+    )
 
 
 if __name__ == "__main__":
-    asyncio.run(HelloLangGraphApp().run())
+    app = BaseCLIApp(
+        app_info=_create_app_info(),
+        agent_configs=AGENT_CONFIGS,
+        settings=get_settings(),
+    )
+    asyncio.run(app.run())

agentic_cli-0.3.1/examples/research_demo/README.md

@@ -0,0 +1,160 @@
+# Research Demo
+
+A demonstration CLI application showcasing all P0/P1 features of the agentic-cli framework.
+
+## Overview
+
+The Research Demo is a research assistant that helps you explore topics while demonstrating:
+
+- **Memory System**: Session-scoped working memory + persistent long-term memory
+- **Task Planning**: Hierarchical task graphs with dependencies
+- **File Operations**: Save, read, and compare research findings
+- **Shell Commands**: Safe command execution with blocking of dangerous patterns
+- **Human-in-the-Loop (HITL)**: Approval gates and review checkpoints
+
+## Running the Demo
+
+```bash
+# From the project root
+conda run -n agenticcli python -m examples.research_demo
+```
+
+## Features
+
+### Memory
+
+The agent can store and recall information across two tiers:
+
+**Working Memory (Session)**
+- Stores context for the current session
+- Cleared when the app exits
+- Use `/memory` to view current state
+
+**Long-term Memory (Persistent)**
+- Stores learnings, facts, preferences, and references
+- Persists to `~/.research_demo/memory/longterm.json`
+- Survives across sessions
+
+### Planning
+
+The agent can create structured research plans:
+
+- Tasks with descriptions and dependencies
+- Status tracking (pending, in_progress, completed, failed)
+- Visual progress display via `/plan` command
+
+### File Operations
+
+- Save research findings to `~/.research_demo/findings/`
+- Compare document versions with diff
+- List and read saved files
+
+### Shell Commands
+
+- Run safe shell commands (ls, cat, grep, etc.)
+- Dangerous commands are blocked (rm -rf, etc.)
+- Timeout protection (30 seconds default)
+
+### HITL
+
+- Approval rules for sensitive operations
+- Auto-approve patterns for safe commands
+- Checkpoints for reviewing agent outputs
+
+## Commands
+
+| Command | Aliases | Description |
+|---------|---------|-------------|
+| `/memory` | `/mem`, `/m` | Show working and long-term memory |
+| `/plan` | `/tasks`, `/p` | Show current task graph |
+| `/files` | `/ls`, `/f` | List files in workspace |
+| `/approvals` | `/approve`, `/a` | Show pending approvals |
+| `/checkpoints` | `/cp`, `/review` | Show checkpoints awaiting review |
+| `/clear-memory` | `/clearmem` | Clear working memory |
+| `/clear-plan` | `/clearplan` | Clear task plan |
+| `/help` | `/h`, `/?` | Show all commands |
+| `/settings` | `/s` | View/change settings |
+| `/exit` | `/quit`, `/q` | Exit the application |
+
+## Example Session
+
+```
+>>> Research the history of Python programming language
+
+[Agent creates a task plan, stores context, and begins researching]
+
+>>> /plan
+
+Progress: 2/5 completed, 1 in progress
+
+✓ Gather initial sources
+✓ Review key events (depends on: Gather initial)
+◐ Document milestones (depends on: Review key events)
+☐ Write summary (depends on: Document milestones)
+☐ Create final report (depends on: Write summary)
+
+>>> /memory
+
+Working Memory (Session)
+┌─────────────────┬───────────────────────┬─────────┐
+│ Key             │ Value                 │ Tags    │
+├─────────────────┼───────────────────────┼─────────┤
+│ research_topic  │ Python history        │ planning│
+│ current_task    │ Document milestones   │         │
+└─────────────────┴───────────────────────┴─────────┘
+
+Long-term Memory (Persistent)
+┌──────────┬──────────┬────────────────────────────────────────────┬──────┐
+│ ID       │ Type     │ Content                                    │ Tags │
+├──────────┼──────────┼────────────────────────────────────────────┼──────┤
+│ a1b2c3d4 │ fact     │ Python was created by Guido van Rossum...  │      │
+│ e5f6g7h8 │ learning │ Python 2.0 introduced list comprehensions  │      │
+└──────────┴──────────┴────────────────────────────────────────────┴──────┘
+
+>>> /files
+
+Files in findings/
+┌─────────────────────────┬──────┬─────────────┐
+│ Name                    │ Type │ Size        │
+├─────────────────────────┼──────┼─────────────┤
+│ python_history_draft.md │ file │ 2,456 bytes │
+│ key_milestones.txt      │ file │ 1,234 bytes │
+└─────────────────────────┴──────┴─────────────┘
+Total: 2 items
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    ResearchDemoApp                          │
+│  (extends BaseCLIApp)                                       │
+├─────────────────────────────────────────────────────────────┤
+│  Commands:                   │  Agent Tools:                │
+│  /memory - show memory state │  remember_context()          │
+│  /plan - show task graph     │  recall_info()               │
+│  /approvals - pending list   │  create_research_plan()      │
+│  /checkpoints - review list  │  update_task_status()        │
+│  /files - list artifacts     │  save_finding()              │
+│  /clear-memory               │  compare_versions()          │
+│  /clear-plan                 │  run_safe_command()          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Configuration
+
+Settings are loaded from environment variables or `~/.research_demo/.env`:
+
+- `GOOGLE_API_KEY` or `ANTHROPIC_API_KEY` - LLM provider API key
+- `RESEARCH_DEMO_WORKSPACE_DIR` - Workspace directory (default: `~/.research_demo`)
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `app.py` | Main CLI application class |
+| `settings.py` | Demo app settings |
+| `agents.py` | Agent configuration with tools |
+| `tools.py` | Tools wrapping new features |
+| `commands.py` | Status commands |
+| `__main__.py` | Entry point |