How dteam-top/tsw-cli works
Project type and purpose
• From the README and file structure, tsw-cli is a Python-based command-line interface that orchestrates “tiny smart workers” (AI/logic modules) to perform tasks like research, code generation, knowledge lookup, summarization, and writing.
• It also includes an “MCP Server” component (under mcp/) for deploying or testing these worker scripts against a local or remote environment.
File structure
Top-level:
• .env.example, .gitignore, README.md, pyproject.toml – project metadata & config
• cli.py – entry point for the command-line tool
• agent/ – core AI-worker modules:
– think.py → orchestration entry
– research.py, code.py, summary.py, writer.py – individual worker steps
– kb.py – knowledge base interface (PostgreSQL)
– settings.py – configuration loader
• lib/ – shared utilities:
– utils.py – helper functions
– pako.py – possibly a compression or packing utility
• mcp/ – scripts to register or explore the workers as services (e.g., kb_exploer.py)
Key insights from the README
• The CLI loads environment variables (via .env), syncs dependencies with uv, then runs cli.py.
• Each command supports a --config to point to alternate settings.
• PostgreSQL (PG) with a default schema ai is used for knowledge storage.
• The “MCP Server” section shows how to register or test scripts in a dev environment.
Main components
A. CLI Layer (cli.py)
B. Agent Pipeline (agent module)
1. Orchestrator (think.py)
2. Worker steps (research.py → code.py → summary.py → writer.py)
3. Knowledge Base interface (kb.py)
C. Utility Library (lib/utils.py, lib/pako.py)
D. Configuration & Environment (.env, settings.py)
E. Data Store (PostgreSQL database schema ai)
F. MCP Server (scripts under mcp/)
G. External Dependencies (e.g., uv CLI tool, Python runtime)
Relationships and interactions
• CLI invokes think.py, passing CLI args and resolved config.
• think.py uses settings.py to load environment variables (from .env or --config).
• The orchestrator calls each worker module in turn, sharing data via in-memory objects.
• When a worker needs facts or context, it calls kb.py → issues SQL queries to the PostgreSQL ai schema.
• Workers may use lib/utils.py for logging, string formatting, retry logic, and lib/pako.py for any data packaging.
• MCP scripts (mcp/kb_exploer.py) interface with the project via uv – registering the script as a service, enabling “dev” mode or “install” mode.
Architectural patterns and design principles
• Modular pipeline: each worker is a single-responsibility component.
• Separation of concerns: CLI vs orchestration vs data persistence vs utilities.
• Pluggable config: environment variables + settings.py + --config override.
• Extensible service registration via the MCP subsystem.