tsugite-cli 0.9.4__tar.gz → 0.10.0__tar.gz

{tsugite_cli-0.9.4 → tsugite_cli-0.10.0}/.gitignore

@@ -167,13 +167,16 @@ cython_debug/
 benchmark_results/
 test_output/
 .claude/settings.local.json
+std*.txt
+secrets/*
 
 
 # TODO: temp - I need to clean up the docs
-docs/
+docs-old/
 examples/
 agents/
 .claude/
 .tsugite/
 benchmarks/
+docker-compose.test.yml
 #### TODO ^^^

{tsugite_cli-0.9.4 → tsugite_cli-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsugite-cli
-Version: 0.9.4
+Version: 0.10.0
 Summary: Micro-agent runner for task automation using markdown definitions
 Author: Justyn Shull
 License: GNU AFFERO GENERAL PUBLIC LICENSE
@@ -239,15 +239,14 @@ License: GNU AFFERO GENERAL PUBLIC LICENSE
         
         You should also get your employer (if you work as a programmer) or school, if any, to sign a "copyright disclaimer" for the program, if necessary. For more information on this, and how to apply and follow the GNU AGPL, see <http://www.gnu.org/licenses/>.
 License-File: LICENSE
-Keywords: agents,automation,cli,jinja2,litellm
+Keywords: agents,automation,cli,jinja2
 Requires-Python: >=3.11
+Requires-Dist: cryptography>=46.0.5
 Requires-Dist: ddgs>=9.6.0
 Requires-Dist: html2text>=2020.1.16
 Requires-Dist: httpx>=0.25
 Requires-Dist: jinja2>=3.1
-Requires-Dist: litellm<1.82.7,>=1.77.7
 Requires-Dist: mcp>=1.0
-Requires-Dist: nest-asyncio>=1.6.0
 Requires-Dist: pathspec>=0.11.0
 Requires-Dist: portalocker>=2.8.0
 Requires-Dist: prompt-toolkit>=3.0.43
@@ -255,6 +254,7 @@ Requires-Dist: pydantic>=2.12.3
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.1.1
 Requires-Dist: rich>=13.0
+Requires-Dist: tiktoken>=0.7.0
 Requires-Dist: typer>=0.12
 Requires-Dist: tzlocal>=5.3.1
 Requires-Dist: youtube-transcript-api>=0.6.0
@@ -269,162 +269,149 @@ Description-Content-Type: text/markdown
 
 # tsugite
 
-Tsugite (Japanese: 継ぎ手, the art of joinery in woodworking) is a developer-facing agentic CLI.
+Tsugite (継ぎ手) is an agent framework where you define AI agents as markdown files and run them from the CLI, a web UI, or through scheduled tasks.
 
-Define AI agents as markdown files with YAML frontmatter. Chain multiple steps together, pass data between them, and use any LLM (OpenAI, Anthropic, Ollama, etc).
+I built it because none of the existing agent frameworks did what I wanted.  I needed something self-hosted, model-agnostic, and simple enough that an agent is just a text file I can edit and version control.
 
-## Installation
+Originally it was meant to be a framework for micro-agents inspired by [ESA](https://github.com/meain/esa), but has grown a lot since that goal.
 
-```bash
-# Recommended: Install with uv
-uv tool install tsugite-cli
-
-# Alternative: Install with pipx
-pipx install tsugite-cli
-
-# Or with pip
-pip install tsugite-cli
-```
-
-**Note:** The package name is `tsugite-cli`, but the command is `tsugite` (or `tsu` for short).
+## What an agent looks like
 
-## Quick Start
+A simple "hello world" agent looks like:
 
-```bash
-# Run an agent
-tsugite run examples/simple_variable_injection.md "test it"
-
-# Create your own agent
-cat > my_agent.md << 'EOF'
+```markdown
 ---
-name: hello
-model: openai:gpt-4o-mini
+name: morning-brief
+model: anthropic:claude-sonnet-4-20250514
+tools: [web_search, fetch_text, write_file, final_answer]
 ---
 
-Task: {{ user_prompt }}
+You are a morning briefing assistant.
 
-Just say hello and use final_answer() to return your greeting.
-EOF
+Current date: {{ now() }}
+User location: {{ env("LOCATION", "unknown") }}
 
-tsugite run my_agent.md "greet the user"
+Check the weather, scan top news, and write a short briefing.
+Use final_answer() to return the result.
 ```
 
-## Features
+YAML frontmatter for config, markdown body for instructions, Jinja for dynamic context.  Run it with:
 
-- **Multi-step workflows** - Chain steps with `<!-- tsu:step -->`, pass data between them
-- **Variable injection** - Step outputs automatically available as Python variables
-- **Multiple LLM providers** - OpenAI, Anthropic, Ollama, Google, GitHub Copilot
-- **MCP integration** - Connect to Model Context Protocol servers
-- **Temperature control** - Set per-step model parameters
-- **Copy-paste friendly output** - `--plain` flag or auto-detection for pipe/redirect
+```bash
+tsu run +morning-brief "what's happening today"
+```
+
+## Key ideas
 
-## CLI Options
+- **Agents are markdown.** A basic agent is just markdown with yaml frontmatter.  Advanced agents are still just markdown but can use jinja templating and a special `<!--tsu -->` syntax.
+- **Code execution over tool-calling.** Inspired by [smolagents](https://github.com/huggingface/smolagents).  Instead of using native tool calling, LLMs write python code.  Tools are exposed as python functions.
+- **Any LLM.** Plugin interface to add support for additional LLM providers.  Built-in we have openai-compatible apis, ollama, anthropic, and claude code.
+- **Workspaces.** Each workspace is a persistent directory with agents, skills, memory files, and config.  The agent runs inside its workspace and can read/write files, spawn sub-agents, manage schedules, and persist state across conversations.  Workspaces are entirely optional.
+- **CLI and/or Daemon with a Web UI** Use `tsu run` commands for cli-only, or run `tsu daemon` for a daemon that supports scheduled tasks, a web ui, and some other neat things.
+
+## Install
 
 ```bash
-# Plain output (no box-drawing characters, copy-paste friendly)
-tsugite run +assistant "task" --plain
+uv tool install tsugite-cli    # recommended
+pipx install tsugite-cli       # alternative
+pip install tsugite-cli        # or plain pip
+```
 
-# Auto-detection: plain mode activates when piped or NO_COLOR is set
-tsugite run +assistant "task" | grep result
+The package is `tsugite-cli`, the command is `tsugite` (or `tsu` for short).
 
-# Headless mode for scripts (result to stdout, progress to stderr)
-tsugite run +assistant "task" --headless
+## Quick start
 
-# Continue latest conversation (auto-detects agent)
-tsugite run --continue "follow-up prompt"
+```bash
+# Initialize a workspace
+tsu init my-workspace
+cd my-workspace
+
+# Run the built-in default agent
+tsu run +default "summarize the files in this directory"
 
-# Continue specific conversation
-tsugite run --continue --conversation-id CONV_ID "follow-up prompt"
-tsugite chat --continue CONV_ID
+# Run an agent file directly
+tsu run my-agent.md "do the thing"
 
-# View conversation history
-tsugite history list
-tsugite history show CONV_ID
+# Start the web UI
+tsu serve
 ```
 
-## Sandbox
+## Features
 
-Agent code can run inside a [bubblewrap](https://github.com/containers/bubblewrap) sandbox with filesystem and network isolation.
+- **Multi-step workflows** with `<!-- tsu:step -->` to chain steps and pass data between them
+- **Scheduling** built-in cron for recurring agent tasks (daily summaries, monitoring, etc.)
+- **Web UI** for conversations, with Discord as an alternative interface
+- **Sub-agents** that can spawn other agents for specific subtasks
+- **Skills** reusable knowledge files agents can load on demand, mostly compatible with [agentskills.io](https://agentskills.io/)
+- **Hooks** that fire shell commands on lifecycle events (post-tool, pre-message, pre/post-compact)
+- **Sandbox** (linux only) via bubblewrap with filesystem and network isolation
+- **KV store** for persistent agent state
+- **MCP** integration for connecting to MCP servers
 
-```bash
-# Sandbox with specific domains allowed
-tsu run +default "task" --sandbox --allow-domain "github.com" --allow-domain "*.openai.com"
+## Agents in more detail
 
-# Full network isolation
-tsu run +default "task" --sandbox --no-network
+Agents support YAML frontmatter for configuration:
+
+```yaml
+---
+name: code-reviewer
+model: anthropic:claude-sonnet-4-20250514
+max_turns: 15
+tools: [read_file, list_files, web_search, final_answer]
+auto_load_skills: [coding-standards]
+---
 ```
 
-**How it works:**
+You can restrict which tools an agent has access to, set turn limits, auto-load skills, attach context files, and extend other agents.  TODO: See `docs/` for the full spec.
 
-```
-CLI --sandbox --allow-domain "*.github.com"
- └─ SubprocessExecutor writes harness script
-     └─ bwrap --unshare-pid --unshare-net --die-with-parent ...
-         └─ TCP↔UDS bridge (HTTP_PROXY → Unix socket)
-             └─ ConnectProxy filters CONNECT requests by domain:port
-```
+Multi-step agents use `<!--tsu -->` comments as directives:
 
-**Default mounts:**
+```markdown
+<!-- tsu:step name="research" model="openai:gpt-4o" -->
+Research the topic and save findings to a variable.
 
-- Read-only: `/usr`, `/lib`, `/lib64`, `/bin`, `/sbin`, `/etc/ssl`, `/etc/resolv.conf`, CA certs, Python venv + `sys.path`
-- Read-write: workspace directory, internal state directory
-- Tmpfs: `/tmp` (fresh each run)
+<!-- tsu:step name="write" -->
+Using the research from the previous step, write a summary.
+The variable `research` is available as a Python variable.
+```
 
-Extra bind mounts can be added programmatically via `SandboxConfig.extra_ro_binds` and `extra_rw_binds`, but these are not yet exposed through CLI flags or agent frontmatter.
+For a complete example, check the built-in [default agent](tsugite/builtin_agents/default.md).
 
-**Network:**
-- Network is namespace-isolated; outbound HTTP/HTTPS goes through a filtering CONNECT proxy
-- Direct connections to bare IP addresses are always blocked
-- `--no-network` skips the proxy entirely — no connectivity at all
+## Sandbox
 
-**`--allow-domain` syntax:**
+On Linux only (for now), agent code runs inside a [bubblewrap](https://github.com/containers/bubblewrap) sandbox when you pass `--sandbox`:
 
-| Pattern | Allows |
-|---|---|
-| `github.com` | ports 80, 443 |
-| `github.com:22` | port 22 only |
-| `*.github.com:8080` | port 8080 on subdomains |
-| `*:*` | all domains, all ports |
+```bash
+tsu run +default "task" --sandbox --allow-domain "github.com"
+tsu run +default "task" --sandbox --no-network
+```
 
-## Hooks
+Filesystem access is limited to the workspace.  Network goes through a filtering proxy that only allows domains you specify.
 
-Hooks fire shell commands at lifecycle points. Configure in `.tsugite/hooks.yaml`:
+## Config and Data Directories
 
-```yaml
-hooks:
-  post_tool:
-    - tools: [write_file]
-      run: git add {{ path }}
-      wait: true
-
-  pre_message:
-    - run: uridx search "{{ message }}" --limit 5
-      capture_as: rag_context
-    - run: cat memory/preferences.md
-      capture_as: user_preferences
-
-  pre_compact:
-    - run: ./scripts/extract-facts.sh {{ turns_file }}
-      wait: true
-
-  post_compact:
-    - run: echo "Compacted {{ turns_compacted }} turns"
-```
+All paths follow [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/) conventions and can be overridden with the standard environment variables.
 
-**Hook fields:** `run` (Jinja2 shell command), `tools` (tool filter, `post_tool` only), `match` (Jinja2 condition), `wait` (block until done), `capture_as` (capture stdout into a template variable, implies `wait`).
+| Path                                   | Default                              | Contents                                     |
+|----------------------------------------|--------------------------------------|----------------------------------------------|
+| `$XDG_CONFIG_HOME/tsugite/`            | `~/.config/tsugite/`                 | `config.json`, `mcp.json`, `daemon.yaml`     |
+| `$XDG_DATA_HOME/tsugite/history/`      | `~/.local/share/tsugite/history/`    | Session history (JSONL per session)          |
+| `$XDG_DATA_HOME/tsugite/daemon/`       | `~/.local/share/tsugite/daemon/`     | Daemon state                                 |
+| `$XDG_DATA_HOME/tsugite/secrets/`      | `~/.local/share/tsugite/secrets/`    | Encrypted secrets (`secrets.db`)             |
+| `$XDG_DATA_HOME/tsugite/kvstore/`      | `~/.local/share/tsugite/kvstore/`    | Key-value store (`kv.db`)                    |
+| `$XDG_DATA_HOME/tsugite/usage/`        | `~/.local/share/tsugite/usage/`      | Usage (cost and token) tracking (`usage.db`) |
+| `$XDG_DATA_HOME/tsugite/workspaces/`   | `~/.local/share/tsugite/workspaces/` | Workspace directories                        |
+| `$XDG_CACHE_HOME/tsugite/attachments/` | `~/.cache/tsugite/attachments/`      | Attachment cache                             |
 
-**Hook types:**
-- **`post_tool`** — After successful tool calls. Context: `tool`, plus tool arguments.
-- **`pre_message`** — Before agent execution. Context: `message`, `user_id`, `agent_name`. Use `capture_as` to inject results into agent templates as `{{ var_name }}`.
-- **`pre_compact`** / **`post_compact`** — Around session compaction. Context: `conversation_id`, `user_id`, `agent_name`, `turns_file`, `turn_count`.
 
 ## Development
 
 ```bash
-# Clone and install for development
 git clone https://github.com/justyns/tsugite.git
 cd tsugite
 uv sync --dev
 ```
 
-See `examples/` for working agents and `CLAUDE.md` for AI-generated documentation.
+## Status
+
+This is a personal project I use daily.  It works for my use cases but isn't polished for general consumption yet.  Issues and PRs welcome, but set expectations accordingly.  Documentation is very sparse because I keep changing things.

tsugite_cli-0.10.0/README.md

@@ -0,0 +1,148 @@
+# tsugite
+
+Tsugite (継ぎ手) is an agent framework where you define AI agents as markdown files and run them from the CLI, a web UI, or through scheduled tasks.
+
+I built it because none of the existing agent frameworks did what I wanted.  I needed something self-hosted, model-agnostic, and simple enough that an agent is just a text file I can edit and version control.
+
+Originally it was meant to be a framework for micro-agents inspired by [ESA](https://github.com/meain/esa), but has grown a lot since that goal.
+
+## What an agent looks like
+
+A simple "hello world" agent looks like:
+
+```markdown
+---
+name: morning-brief
+model: anthropic:claude-sonnet-4-20250514
+tools: [web_search, fetch_text, write_file, final_answer]
+---
+
+You are a morning briefing assistant.
+
+Current date: {{ now() }}
+User location: {{ env("LOCATION", "unknown") }}
+
+Check the weather, scan top news, and write a short briefing.
+Use final_answer() to return the result.
+```
+
+YAML frontmatter for config, markdown body for instructions, Jinja for dynamic context.  Run it with:
+
+```bash
+tsu run +morning-brief "what's happening today"
+```
+
+## Key ideas
+
+- **Agents are markdown.** A basic agent is just markdown with yaml frontmatter.  Advanced agents are still just markdown but can use jinja templating and a special `<!--tsu -->` syntax.
+- **Code execution over tool-calling.** Inspired by [smolagents](https://github.com/huggingface/smolagents).  Instead of using native tool calling, LLMs write python code.  Tools are exposed as python functions.
+- **Any LLM.** Plugin interface to add support for additional LLM providers.  Built-in we have openai-compatible apis, ollama, anthropic, and claude code.
+- **Workspaces.** Each workspace is a persistent directory with agents, skills, memory files, and config.  The agent runs inside its workspace and can read/write files, spawn sub-agents, manage schedules, and persist state across conversations.  Workspaces are entirely optional.
+- **CLI and/or Daemon with a Web UI** Use `tsu run` commands for cli-only, or run `tsu daemon` for a daemon that supports scheduled tasks, a web ui, and some other neat things.
+
+## Install
+
+```bash
+uv tool install tsugite-cli    # recommended
+pipx install tsugite-cli       # alternative
+pip install tsugite-cli        # or plain pip
+```
+
+The package is `tsugite-cli`, the command is `tsugite` (or `tsu` for short).
+
+## Quick start
+
+```bash
+# Initialize a workspace
+tsu init my-workspace
+cd my-workspace
+
+# Run the built-in default agent
+tsu run +default "summarize the files in this directory"
+
+# Run an agent file directly
+tsu run my-agent.md "do the thing"
+
+# Start the web UI
+tsu serve
+```
+
+## Features
+
+- **Multi-step workflows** with `<!-- tsu:step -->` to chain steps and pass data between them
+- **Scheduling** built-in cron for recurring agent tasks (daily summaries, monitoring, etc.)
+- **Web UI** for conversations, with Discord as an alternative interface
+- **Sub-agents** that can spawn other agents for specific subtasks
+- **Skills** reusable knowledge files agents can load on demand, mostly compatible with [agentskills.io](https://agentskills.io/)
+- **Hooks** that fire shell commands on lifecycle events (post-tool, pre-message, pre/post-compact)
+- **Sandbox** (linux only) via bubblewrap with filesystem and network isolation
+- **KV store** for persistent agent state
+- **MCP** integration for connecting to MCP servers
+
+## Agents in more detail
+
+Agents support YAML frontmatter for configuration:
+
+```yaml
+---
+name: code-reviewer
+model: anthropic:claude-sonnet-4-20250514
+max_turns: 15
+tools: [read_file, list_files, web_search, final_answer]
+auto_load_skills: [coding-standards]
+---
+```
+
+You can restrict which tools an agent has access to, set turn limits, auto-load skills, attach context files, and extend other agents.  TODO: See `docs/` for the full spec.
+
+Multi-step agents use `<!--tsu -->` comments as directives:
+
+```markdown
+<!-- tsu:step name="research" model="openai:gpt-4o" -->
+Research the topic and save findings to a variable.
+
+<!-- tsu:step name="write" -->
+Using the research from the previous step, write a summary.
+The variable `research` is available as a Python variable.
+```
+
+For a complete example, check the built-in [default agent](tsugite/builtin_agents/default.md).
+
+## Sandbox
+
+On Linux only (for now), agent code runs inside a [bubblewrap](https://github.com/containers/bubblewrap) sandbox when you pass `--sandbox`:
+
+```bash
+tsu run +default "task" --sandbox --allow-domain "github.com"
+tsu run +default "task" --sandbox --no-network
+```
+
+Filesystem access is limited to the workspace.  Network goes through a filtering proxy that only allows domains you specify.
+
+## Config and Data Directories
+
+All paths follow [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/) conventions and can be overridden with the standard environment variables.
+
+| Path                                   | Default                              | Contents                                     |
+|----------------------------------------|--------------------------------------|----------------------------------------------|
+| `$XDG_CONFIG_HOME/tsugite/`            | `~/.config/tsugite/`                 | `config.json`, `mcp.json`, `daemon.yaml`     |
+| `$XDG_DATA_HOME/tsugite/history/`      | `~/.local/share/tsugite/history/`    | Session history (JSONL per session)          |
+| `$XDG_DATA_HOME/tsugite/daemon/`       | `~/.local/share/tsugite/daemon/`     | Daemon state                                 |
+| `$XDG_DATA_HOME/tsugite/secrets/`      | `~/.local/share/tsugite/secrets/`    | Encrypted secrets (`secrets.db`)             |
+| `$XDG_DATA_HOME/tsugite/kvstore/`      | `~/.local/share/tsugite/kvstore/`    | Key-value store (`kv.db`)                    |
+| `$XDG_DATA_HOME/tsugite/usage/`        | `~/.local/share/tsugite/usage/`      | Usage (cost and token) tracking (`usage.db`) |
+| `$XDG_DATA_HOME/tsugite/workspaces/`   | `~/.local/share/tsugite/workspaces/` | Workspace directories                        |
+| `$XDG_CACHE_HOME/tsugite/attachments/` | `~/.cache/tsugite/attachments/`      | Attachment cache                             |
+
+
+## Development
+
+```bash
+git clone https://github.com/justyns/tsugite.git
+cd tsugite
+uv sync --dev
+```
+
+## Status
+
+This is a personal project I use daily.  It works for my use cases but isn't polished for general consumption yet.  Issues and PRs welcome, but set expectations accordingly.  Documentation is very sparse because I keep changing things.