Metadata-Version: 2.4
Name: tilde-agent
Version: 0.1.1
Summary: A production-grade, terminal-based AI/Agentic coding harness with enhanced security
Keywords: ai,agent,coding,terminal,tui,productivity,automation
Author: tilde Team
Author-email: tilde Team <tilde@example.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Terminals
Classifier: Topic :: Text Editors
Requires-Dist: rich>=13.7.0
Requires-Dist: textual>=4.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: openai>=1.0.0
Requires-Dist: anthropic>=0.40.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: structlog>=23.2.0
Requires-Dist: opentelemetry-api>=1.21.0
Requires-Dist: opentelemetry-sdk>=1.21.0
Requires-Dist: sqlmodel>=0.0.14
Requires-Dist: mcp>=1.0.0
Requires-Dist: typing-extensions>=4.9.0
Requires-Dist: tilde-agent[dev] ; extra == 'all'
Requires-Dist: tilde-agent[security] ; extra == 'all'
Requires-Dist: tilde-agent[browser] ; extra == 'all'
Requires-Dist: tilde-agent[github] ; extra == 'all'
Requires-Dist: playwright>=1.40.0 ; extra == 'browser'
Requires-Dist: pytest>=7.4.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
Requires-Dist: ruff>=0.1.0 ; extra == 'dev'
Requires-Dist: mypy>=1.8.0 ; extra == 'dev'
Requires-Dist: pyright>=1.1.0 ; extra == 'dev'
Requires-Dist: mkdocs>=1.5.0 ; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5.0 ; extra == 'dev'
Requires-Dist: pygithub>=2.1.1 ; extra == 'github'
Requires-Dist: ghapi>=1.0.0 ; extra == 'github'
Requires-Dist: bandit>=1.7.0 ; extra == 'security'
Requires-Dist: safety>=2.3.0 ; extra == 'security'
Requires-Python: >=3.12, <3.14
Project-URL: Homepage, https://github.com/Chmgx81/tilde
Project-URL: Documentation, https://github.com/Chmgx81/tilde#readme
Project-URL: Repository, https://github.com/Chmgx81/tilde.git
Project-URL: Issues, https://github.com/Chmgx81/tilde/issues
Provides-Extra: all
Provides-Extra: browser
Provides-Extra: dev
Provides-Extra: github
Provides-Extra: security
Description-Content-Type: text/markdown

# tilde (~)

> **A production-grade, terminal-based AI/Agentic coding harness with enhanced security**

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-yellow.svg)](https://github.com/astral-sh/ruff)

---

## 🚀 Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/Chmgx81/tilde.git
cd tilde

# Install with uv (recommended)
uv sync

# Or install in development mode
uv pip install -e .
```

### Usage

```bash
# Start interactive mode (default)
tilde

# Continue a session
tilde --continue

# Use a specific model
tilde --model gpt-4 --provider openai

# Run in JSON mode
tilde --mode json "List all Python files"

# Run in print mode (single response)
tilde --mode print "What's in this directory?"

# Attach files (repeatable --file option)
tilde --file src/main.py "Review this code"

# Shell commands run via shell mode: type ! at the start of the
# composer input line in the interactive TUI (amber border).
# Example: !ls -la
```

---

## ⚡ Features

### ✅ Implemented
- [x] Project structure and initialization
- [x] CLI with Typer (interactive, `--mode json|rpc|print`, `--continue`, `--model`, `--provider`)
- [x] Agent runtime (model providers, tool registry, sessions, compaction, queue)
- [x] Tool system (read, write, edit, bash, grep, find, ls, web_search, browser, sysinfo, github, subagent, skill)
- [x] TUI with Rich + Textual (header, transcript, composer, footer, approval modal, inspector modal, NO_COLOR / reduced-motion / ASCII glyphs, output collapsing, `/doctor`, `?` help)
- [x] MCP support, skills system, subagents, plan mode (`--plan`), accept-edits mode (`--accept-edits`)
- [x] Policy engine with ASK approval tier + audit trail, session persistence (JSONL)
- [x] Sandbox execution, logging (structlog), tracing (OpenTelemetry), 200+ unit tests

### 🚧 In Development
- [ ] Extended tool coverage and hardening (secret redaction in sessions, untrusted-output marking — task_0005)
- [ ] Ruff baseline: format + lint clean (task_0002 in progress)

### 📋 Planned
- [ ] Enhanced security (7-Pillar architecture) — partially done (policy, sandbox, audit); remaining: prompt-injection protection, sensitive-data handling
- [ ] System monitoring (beyond sysinfo tool)
- [ ] Security auditing (beyond audit tooling)
- [ ] Extensions/plugins + package system
- [ ] Polish: comprehensive docs, packaging, CI/CD

---

## 🏗️ Architecture

tilde follows a **layered architecture** with clear separation of concerns:

```
┌─────────────────────────────────────────────────────────────┐
│                    Agent Runtime (Harness)                       │
│  model/      - LLM provider integrations (OpenAI, etc.)        │
│  tools/     - Built-in tools (read, write, bash, etc.)           │
│  session/   - Session management and compaction                 │
│  queue/     - Message queue (steering, follow-up)                │
│  context/   - Context file loading (AGENTS.md, etc.)             │
│  policy/    - Security policies and permissions                  │
└──────────────────────────┬────────────────────────────────────┘
                           ↓ typed events + snapshots
┌──────────────────────────▼────────────────────────────────────┐
│                    UI State Store                               │
│  transcript/   - Conversation history                           │
│  execution/   - Current execution state                         │
│  composer/    - Input composer state                            │
│  overlay/     - Overlays and modals                             │
└──────────────────────────┬────────────────────────────────────┘
                           ↓ render model
┌──────────────────────────▼────────────────────────────────────┐
│                    TUI Runtime                                  │
│  app.py       - Main Textual application                       │
│  layout.py    - Layout system (VStack, HStack, ScrollView)       │
│  rendering/  - Differential rendering                           │
│  input.py     - Input handling (keyboard, mouse, paste, IME)     │
│  terminal/   - Terminal abstraction                             │
│  components/ - UI components (header, transcript, composer)      │
│  themes/     - Color themes and design tokens                   │
└──────────────────────────┬────────────────────────────────────┘
                           ↓ ANSI / synchronized I/O
┌──────────────────────────▼────────────────────────────────────┐
│                    Terminal                                     │
└───────────────────────────────────────────────────────────────┘
```

---

## 🎯 Design Principles

### Core Philosophy
1. **Plan First**: Always plan before executing code
2. **Security First**: 7-Pillar security architecture
3. **Harness > Model**: The scaffolding matters more than the model
4. **Spec-Driven**: Write specifications before implementation
5. **Context Engineering**: Manage context window carefully

### User Experience
1. **Safety > Convenience**: Decision surfaces beat decoration
2. **Minimal Animation**: Only spinner and streaming updates
3. **Quiet When Idle**: No animation when not working
4. **History Preservation**: Stable, selectable, copyable, searchable

---

## 📦 Tech Stack

| Category | Technology | Purpose |
|----------|------------|---------|
| **Language** | Python 3.12+ | Primary language |
| **Package Manager** | uv | Fast dependency management |
| **TUI Framework** | Textual | Event loop, layout, rendering |
| **Rendering** | Rich | Beautiful text rendering |
| **CLI** | Typer | Command-line interface |
| **LLM** | OpenAI SDK | Model interactions |
| **HTTP** | httpx | Async HTTP requests |
| **Data Validation** | Pydantic | Data models and validation |
| **Settings** | pydantic-settings | Configuration management |
| **Observability** | structlog + OpenTelemetry | Logging and tracing |
| **Database** | SQLModel + SQLite | Session storage |
| **MCP** | mcp Python SDK | Model Context Protocol |
| **Parsing** | tree-sitter, difflib | Code parsing and diffs |
| **Testing** | pytest + pytest-asyncio | Test framework |
| **Linting** | Ruff | Fast linting |
| **Type Checking** | mypy / pyright | Static type checking |

---

## 📂 Project Structure

```
tilde/
├── src/tilde/                    # Main source code
│   ├── __init__.py               # Package initialization
│   ├── main.py                   # Entry point
│   ├── cli.py                    # CLI with Typer
│   ├── logging.py                # structlog setup
│   ├── tracing.py                # OpenTelemetry setup
│   ├── runtime/                  # Agent runtime
│   │   ├── agent.py              # Main AgentRuntime class
│   │   ├── context.py            # Context file loading (flat module)
│   │   ├── policy.py             # Policy engine (flat module)
│   │   ├── queue.py              # Message queue (flat module)
│   │   ├── sandbox.py            # Sandbox execution
│   │   ├── skills.py             # Skills discovery
│   │   ├── mcp.py                # MCP integration
│   │   ├── model/                # Model providers
│   │   │   ├── __init__.py
│   │   │   ├── base.py           # Base ModelProvider
│   │   │   ├── openai.py         # OpenAI provider
│   │   │   ├── anthropic.py      # Anthropic provider
│   │   │   └── openrouter.py     # OpenRouter provider
│   │   ├── tools/                # Built-in tools
│   │   │   ├── __init__.py       # Tool registry
│   │   │   ├── base.py           # Base Tool class
│   │   │   ├── read.py           # Read tool
│   │   │   ├── write.py          # Write tool
│   │   │   ├── edit.py           # Edit tool
│   │   │   ├── bash.py           # Bash tool
│   │   │   ├── grep.py           # Grep tool
│   │   │   ├── find.py           # Find tool
│   │   │   ├── ls.py             # Ls tool
│   │   │   ├── web_search.py     # Web search tool
│   │   │   ├── browser.py        # Browser tool
│   │   │   ├── sysinfo.py        # System info tool
│   │   │   ├── github.py         # GitHub tool
│   │   │   ├── subagent.py       # Subagent tool
│   │   │   └── skill.py          # Skill tool
│   │   ├── session/              # Session management
│   │   │   ├── __init__.py
│   │   │   ├── manager.py        # Session manager (JSONL)
│   │   │   └── compaction.py     # Compaction engine
│   │   └── modes/                # Runtime modes
│   │       ├── __init__.py
│   │       ├── interactive.py    # Interactive TUI mode
│   │       ├── json_mode.py      # JSON event-stream mode
│   │       ├── rpc_mode.py       # JSON-RPC mode
│   │       └── print_mode.py     # Single-response print mode
│   ├── state/                    # UI state management
│   │   ├── __init__.py           # UIState container
│   │   ├── transcript.py         # Transcript state
│   │   ├── execution.py          # Execution state
│   │   ├── composer.py           # Composer state
│   │   ├── context.py            # Context state
│   │   └── inspector.py          # Inspector state
│   └── tui/                      # Terminal UI
│       ├── __init__.py
│       ├── app.py                # Main Textual app
│       ├── display.py            # NO_COLOR / motion / glyph / collapse / doctor / help
│       ├── components/           # UI components
│       │   ├── __init__.py
│       │   ├── header.py         # Header component
│       │   ├── transcript.py     # Transcript component
│       │   ├── composer.py       # Composer component
│       │   ├── footer.py         # Footer component
│       │   ├── approval.py       # Approval modal
│       │   └── inspector.py      # Inspector modal
│       └── themes/               # Color themes
│           ├── __init__.py
│           └── tokens.py         # Design tokens (tui-spec.md section 5.1)
├── tests/                        # Tests (36 unit files, 233 green)
│   ├── unit/                     # Unit tests
│   ├── integration/              # Integration tests (empty, TODO)
│   └── e2e/                      # End-to-end tests (empty, TODO)
├── docs/                         # Documentation
│   └── INSPIRATION_SUMMARY.md    # Key learnings from references
├── .pi/agent/                    # Pi config (skills/, extensions/ - empty, TODO)
├── .github/workflows/              # GitHub Actions (empty, TODO)
├── pyproject.toml                # Project configuration
├── progress.md                   # Project progress tracker
├── AGENTS.md                     # Agent instructions and context
├── Plan.md                       # Master project plan
├── tui-spec.md                   # TUI design specification
└── README.md                     # This file
```

---

## 🛡️ Security

tilde implements the **7-Pillar Agent Security Architecture**:

1. **Infrastructure & Networking**: Sandboxing, network egress governance
2. **Data**: Encryption, access controls, tenant partitioning
3. **Model**: Prompt validation, output filtering, instruction security
4. **Application & Runtime**: LLM firewalls, lifecycle hooks, agent gateways
5. **IAM**: Agent identities, ABAC, JIT token downscoping
6. **Observability**: OpenTelemetry, behavioral analytics, audit trails
7. **Governance**: Compliance, risk assessment, attestation

---

## 📖 Documentation

- **[Plan.md](./Plan.md)** - Master project plan and vision
- **[tui-spec.md](./tui-spec.md)** - TUI design specification (contract)
- **[AGENTS.md](./AGENTS.md)** - Development guidelines and project context
- **[progress.md](./progress.md)** - Project progress tracker (start here!)
- **[docs/INSPIRATION_SUMMARY.md](./docs/INSPIRATION_SUMMARY.md)** - Key learnings from reference materials

---

## 🤝 Contributing

See **[AGENTS.md](./AGENTS.md)** for development guidelines.

### Quick Contribution Guide

1. **Read progress.md** - Understand current state
2. **Check open questions** - See if your question is already answered
3. **Follow the workflow** - Research → Plan → Explain → Implement → Test → Document
4. **Update progress.md** - Track your changes
5. **Keep it simple** - Don't over-engineer
6. **Explain simply** - Use dead-simple English

---

## 📜 License

MIT License - see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

tilde is inspired by and builds upon the excellent work of:
- **[Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent)** - Primary inspiration
- **[Agent Skills Standard](https://agentskills.io)** - Skills system
- **[Model Context Protocol](https://github.com/modelcontextprotocol/specification)** - Tool interoperability
- **[Rich](https://github.com/Textualize/rich)** - Beautiful terminal rendering
- **[Textual](https://github.com/Textualize/textual)** - TUI framework

---

## 💬 Community

- **Issues**: [GitHub Issues](https://github.com/Chmgx81/tilde/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Chmgx81/tilde/discussions)

---

> **Remember**: tilde is always **plan first** - it always plans before executing any code.
