tiiny-sdk 0.2.0

A minimal agent CLI with provider abstraction, tool calling, and system prompt assembly.

tiiny-cli

tiiny-cli is a minimal agent runtime inspired by the architecture of hermes-agent, but intentionally scoped down to four core parts:

• agent loop
• provider abstraction
• tool calling
• system prompt construction

The goal of this first cut is to give you a small, readable foundation that you can extend without carrying the full complexity of Hermes.

What is included

• A session-oriented Agent loop
• OpenAI-compatible provider adapter
• Tool registry with JSON-schema tool definitions
• Toolset-based filtering for session-scoped tool surfaces
• Minimal built-in tools for local development
• Minimal built-in tools for local development, including webpage fetch
• Skill discovery, loading, and management tools
• Hermes-style SOUL.md, AGENT.md, USER.md, and MEMORY.md support
• Layered system prompt builder
• JSON-backed session persistence with stable system prompt caching
• Streaming assistant output and live tool progress in the CLI
• CLI entrypoint for one-shot and interactive use

Quick start

cd tiiny-cli
python -m venv .venv
source .venv/bin/activate
pip install -e .
export OPENAI_API_KEY=your_key
export OPENAI_API_URL=http://127.0.0.1:8000/v1
export TIINY_MODEL=gpt-4.1-mini

tiiny "List the files in the current directory"

Interactive mode:

tiiny

Configuration mode:

tiiny config

Running plain tiiny starts a fresh auto-generated session by default. Use --session <name> if you want to continue an existing session.

Inside interactive mode you can use:

• /new to start a fresh session with an auto-generated name
• /new my-session to switch to a specific new session name
• /tasks to list active background shell tasks
• /stop or /stop all to stop all active background shell tasks launched by this tiiny process
• /stop <task_id> to stop one active background shell task

Use a named session to preserve history across runs:

tiiny --session backend "inspect the current project"
tiiny --session backend "now summarize what you found"

Restrict the tool surface to specific toolsets:

tiiny --list-toolsets
tiiny --enable-toolset filesystem "read the README and summarize it"
tiiny --disable-toolset terminal "inspect the project structure safely"

Use tiiny config to manage persistent agent files and Tiiny home:

tiiny config
tiiny config home
tiiny config soul
tiiny config agent
tiiny config user
tiiny config memory

tiiny config lets you:

• change the base tiiny-home directory
• edit the contents of SOUL.md
• edit the contents of AGENT.md
• edit the contents of USER.md
• edit the contents of MEMORY.md

The CLI streams assistant text as it is generated and prints tool activity in between iterations, so interactive runs feel closer to Hermes instead of waiting for one final block response.

Interactive input uses prompt_toolkit, which gives much better editing behavior for Chinese and other wide-character input than plain input().

Skills are stored under ~/.tiiny/skills by default. Once the skills toolset is enabled, the agent can:

• list skills with skills_list
• load a skill with skill_view
• create or update skills with skill_manage

Tiiny also supports Hermes-style persona and memory files:

• ~/.tiiny/SOUL.md: persistent agent identity and high-level behavior
• ~/.tiiny/AGENT.md: stable operating instructions for future sessions
• ~/.tiiny/USER.md: stable user preferences and workflow habits
• ~/.tiiny/MEMORY.md: durable project/environment facts and conventions

On first startup, Tiiny bootstraps these files automatically if they do not exist yet. The active tiiny-home directory is stored in ~/.tiiny/config.json unless you override it with TIINY_HOME.

Environment variables

• OPENAI_API_KEY: API key for the OpenAI-compatible provider
• OPENAI_API_URL: Preferred base URL variable for local or self-hosted OpenAI-compatible endpoints
• OPENAI_BASE_URL: Optional custom OpenAI-compatible base URL
• TIINY_ENABLE_THINKING: Whether to send extra_body.chat_template_kwargs.enable_thinking on model calls, default true
• TIINY_MODEL: Model name, default gpt-4.1-mini
• TIINY_MAX_ITERATIONS: Agent loop cap, default 12
• TIINY_SYSTEM_PROMPT: Optional extra stable system prompt content
• TIINY_EPHEMERAL_SYSTEM_PROMPT: Optional per-run ephemeral prompt suffix
• TIINY_ENABLED_TOOLSETS: Comma-separated allowlist, for example filesystem,terminal
• TIINY_DISABLED_TOOLSETS: Comma-separated denylist
• TIINY_SESSION_HOME: Session storage directory, default <tiiny_home>/sessions
• TIINY_SKILL_HOME: Skill storage directory, default <tiiny_home>/skills
• TIINY_HOME: Base Tiiny home directory, default ~/.tiiny
• TIINY_SOUL_PATH: Advanced override for SOUL.md, default <tiiny_home>/SOUL.md
• TIINY_AGENT_PATH: Advanced override for AGENT.md, default <tiiny_home>/AGENT.md
• TIINY_USER_PATH: Advanced override for USER.md, default <tiiny_home>/USER.md
• TIINY_MEMORY_PATH: Advanced override for MEMORY.md, default <tiiny_home>/MEMORY.md
• TIINY_WEB_SEARCH_URL: Override the default web search service endpoint

Architecture

CLI
  -> Agent
    -> SessionStore
    -> SkillStore
    -> MemoryStore
    -> PromptBuilder
    -> Provider
    -> ToolRegistry
      -> Built-in tool handlers

Key files:

• src/tiiny_cli/agent.py: main loop
• src/tiiny_cli/session.py: JSON-backed session persistence
• src/tiiny_cli/memory.py: SOUL.md, AGENT.md, USER.md, MEMORY.md storage and frozen prompt snapshots
• src/tiiny_cli/skills.py: local skill storage, metadata parsing, and prompt integration
• src/tiiny_cli/prompt_builder.py: system prompt assembly
• src/tiiny_cli/providers/openai_compatible.py: provider adapter
• src/tiiny_cli/tools/registry.py: schema registry and dispatch
• src/tiiny_cli/tools/builtin.py: starter tools
• src/tiiny_cli/tools/memory.py: persistent memory tool
• src/tiiny_cli/tools/skills.py: skill tools

Built-in toolsets

• filesystem: list_directory, read_file, write_file
• terminal: run_command, bash, process, detect_browser
• web: web_search, fetch_webpage
• memory: memory
• skills: skills_list, skill_view, skill_manage

Web Search And Fetch

Tiiny includes Hermes-inspired web search and fetch tools:

• web_search: query the configured search service and return candidate URLs
• fetch_webpage: fetch one or more public HTTP(S) pages, extract readable text, and optionally focus the result with a query

Recommended flow:

• call web_search first to discover relevant URLs
• call fetch_webpage on the most relevant results to inspect page content

Example:

Use web_search with:
{
  "query": "OpenAI latest research",
  "topk": 5
}

Then use fetch_webpage with:
{
  "urls": ["https://example.com"],
  "query": "domain reserved example"
}

The tool blocks localhost and private-network addresses to avoid unsafe internal fetches. The search endpoint defaults to http://34.212.123.29:8002/api/retrieve and can be overridden with TIINY_WEB_SEARCH_URL.

Browser Detection

Tiiny includes a Hermes-inspired browser detection helper:

• detect_browser: detect Chrome-family browsers across macOS, Windows, and Linux

Use it when a workflow depends on a local browser being installed. This avoids false negatives from Linux-only checks like which google-chrome on macOS.

SOUL And Memory Files

On first startup, Tiiny bootstraps the following files under ~/.tiiny by default:

• SOUL.md: top-level identity
• AGENT.md: durable operating instructions
• USER.md: user preferences and working style
• MEMORY.md: durable facts about the environment or project

If you already have older files under ~/.tiiny/memories/, Tiiny migrates them to the tiiny-home root automatically on startup.

If SOUL.md exists, Tiiny uses it as the top-level identity layer instead of the built-in default identity string.

AGENT.md, USER.md, and MEMORY.md are loaded as a frozen snapshot at session start and injected into the system prompt. Mid-session writes through the memory tool update the files on disk immediately, but they do not rewrite the current session prompt; the new snapshot is picked up the next time a fresh session starts.

Example layout:

~/.tiiny/
  SOUL.md
  AGENT.md
  USER.md
  MEMORY.md

Skill layout

Each skill lives in its own directory and contains a required SKILL.md.

~/.tiiny/skills/
  my-skill/
    SKILL.md
    references/
    templates/
    scripts/
    assets/

Minimal SKILL.md format:

---
name: my-skill
description: Short explanation of when to use this skill.
---

# My Skill

Step-by-step instructions go here.

Notes

This is a starter architecture, not a production-hardening pass. The current built-in tools include file reads, file writes, directory listing, and shell command execution, so you should review and tighten permissions before wider use.

Live CLI behavior

• Assistant text is streamed token-by-token when the provider supports OpenAI-compatible streaming.
• Tool calls are shown in a structured live activity feed with clearer visual separation.
• A lightweight spinner keeps the CLI feeling active between model/tool events.
• The bash tool is the direct shell-facing alias for terminal work; run_command remains available as a more generic name.
• bash and run_command can take background=true.
• The process tool can list, status, wait, stop, and stop_all background tasks.
• /tasks, /stop all, and /stop <task_id> control those background tasks from the interactive CLI.