Metadata-Version: 2.4
Name: openturtles
Version: 0.12.0
Summary: OpenTurtles CLI — AI That Acts in the Real World. Say one sentence, get an AI agent that runs forever.
License: Proprietary
Project-URL: Homepage, https://openturtles.ai
Project-URL: Documentation, https://openturtles.ai/docs
Project-URL: Repository, https://github.com/openturtles/cli
Keywords: ai,agents,autonomous,cli,turtles,openturtles,automation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Home Automation
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown

<div align="center">

<img src="https://raw.githubusercontent.com/openturtles/cli/refs/heads/main/assets/logo.svg" alt="OpenTurtles" width="280" />

# OpenTurtles

### Say one sentence. Get an AI that acts on it — forever.

**AI That Acts in the Real World.**

[![Version](https://img.shields.io/badge/version-v0.12.0-00e87b?style=flat-square)](https://openturtles.ai)
[![Status](https://img.shields.io/badge/status-shipped-00e87b?style=flat-square)](https://openturtles.ai)
[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-00e87b?style=flat-square)](#installation)
[![Built with Rust](https://img.shields.io/badge/built%20with-Rust-00e87b?style=flat-square&logo=rust)](https://www.rust-lang.org)
[![Stars](https://img.shields.io/github/stars/openturtles/cli?style=flat-square&color=00e87b&logo=github)](https://github.com/openturtles/cli/stargazers)

[**Website**](https://openturtles.ai) · [**Documentation**](https://openturtles.ai/docs) · [**Live Map**](https://openturtles.ai/live) · [**Explore Turtles**](https://openturtles.ai/explore)

</div>

---

## ✨ What is OpenTurtles?

**OpenTurtles** turns a single sentence into a living, autonomous AI agent — a **Turtle** — that watches your world, acts on it, and evolves over time.

> *"Remind me to stand up every 25 minutes."*
> *"Turn off the lights when I leave the room."*
> *"Catch me slacking off and nudge me back."*

One sentence creates a Turtle. It runs in the background, observes your environment, takes action, and **gets smarter the longer it lives** — so you don't have to.

### A Whole New Quadrant

Not a chatbot. Not a cron job. Not a dev framework. OpenTurtles creates something entirely new.

<div align="center">

|                       | **Stops After Reply**                                          | **Acts Forever**                                                              |
| :-------------------- | :------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| **Natural Language**  | 💬 **ChatGPT**<br/>Conversational AI<br/>Answers once, then stops | 🐢 **OpenTurtles** ✦ *New Quadrant*<br/>One sentence · Compile once<br/>Watches, acts, evolves — forever |
| **Requires Coding**   | 🔧 **LangChain / Agents**<br/>Developer framework<br/>Calls LLM every time, requires code | ⏰ **Cron / RPA**<br/>Fixed scripts<br/>No understanding, no evolution |

</div>

---

## 🚀 Installation

### One-line install (macOS / Linux)

```bash
curl -fsSL https://openturtles.ai/install.sh | bash
```

### Manual download

Grab a prebuilt binary from the [latest release](https://github.com/openturtles/cli/releases):

| Platform             | Architecture | Archive                                       |
| :------------------- | :----------- | :-------------------------------------------- |
| macOS Apple Silicon  | `aarch64`    | `turtles-v0.12.0-darwin-aarch64.tar.gz`       |
| macOS Intel          | `x86_64`     | `turtles-v0.12.0-darwin-x86_64.tar.gz`        |
| Linux                | `x86_64`     | `turtles-v0.12.0-linux-x86_64.tar.gz`         |
| Linux                | `aarch64`    | `turtles-v0.12.0-linux-aarch64.tar.gz`        |

```bash
tar -xzf turtles-v0.12.0-<platform>.tar.gz
sudo mv turtles /usr/local/bin/
turtles --version
```

## ⚡ Quick Start (5 minutes)

Get your first Turtle running in 3 steps.

**Step 1 — Log in**

```bash
$ turtles login
✓ Logged in as openturtles
```

**Step 2 — Create a Turtle**

```bash
$ turtles create "Remind me to drink water every hour from 9am to 6pm"
⠋ Compiling...
✓ WaterReminder created and started (PID: 12345)
```

**Step 3 — Watch it run**

```bash
$ turtles watch WaterReminder
[09:00] 💧 Reminder: Time to drink water!
[10:00] 💧 Reminder: Time to drink water!
[11:02] 💧 Reminder: Time to drink water!
```

That's it. Your Turtle is running in the background, forever.

### Deploy it to OpenTurtles (optional)

Push it to your dashboard or share it on the Live Map:

```bash
$ turtles deploy WaterReminder

  🐢 Deploying WaterReminder to OpenTurtles

  Visibility:
  ❯ Public — visible on your profile and discoverable by anyone
    Private — only visible to you on your dashboard

  ✓ Deployed WaterReminder to OpenTurtles!

  View on OpenTurtles:
    https://openturtles.ai/openturtles/WaterReminder
```

Deploying is entirely optional — your Turtle works the same whether deployed or not.

---

## 🧠 From Zero to Act

No code. No config files. Just one sentence.

### 3 steps — that's it

**01 · Say What You Want**
Describe what you need in plain language.
> *"Remind me to stand up every 25 minutes"*

**02 · AI Compiles It**
AI understands your intent and generates a live turtle.
**Compiled once. Runs forever. Zero ongoing cost.**

**03 · It Watches, Acts, Evolves**
Runs in the background. Observes your world, takes action, and gets smarter over time.

### See it in action

```bash
# Step 1 — Create a Turtle with one sentence
$ turtles create "Turn on heater below 18°C, AC above 26°C"
  ⠋ Compiling...
  ✓ HomeKeep created & started (PID: 12345)

# Step 2 — Watch it work in real-time
$ turtles watch HomeKeep
  [14:30] 🐢 HomeKeep │ 🌡️ 21.5°C — normal range
  [14:31] 🐢 HomeKeep │ 🧬 Auto-evolved: weekend threshold 17°C
  [22:00] 🐢 HomeKeep │ 💡 You left — turned off 3 lights

# Step 3 — Deploy to the global network
  ✓ Deployed to https://openturtles.ai/@openturtles/HomeKeep
  🌍 Now visible on the Global Turtle Network
```

---

## 🌱 Self-Evolution Timeline

A Turtle isn't a script. It's a living process. Here's what happens after you create one:

| Phase      | What it does                                                              |
| :--------- | :------------------------------------------------------------------------ |
| **Day 7**  | Starts recording environment data (`observe("idle_seconds", 16.7, ...)`)  |
| **Day 30** | Discovers patterns (*"weekend idle threshold is longer"*)                 |
| **Day 90** | Auto-tunes its own config variables (`AWAY_THRESHOLD: 300→240`, confidence 0.92) |
| **Day 365**| Fully autonomous. Hundreds of evolutions. Zero human intervention.        |

> Only configuration variables evolve — never the logic. Your Turtle gets smarter without ever going rogue.

---

## 🐢 What You Can Build

A few real examples from the community — every one of them is a single sentence away.

| Domain            | Turtles                                                          |
| :---------------- | :--------------------------------------------------------------- |
| 🩺 **Health**     | WaterTrack · EyeGuard · PostureCheck · StandupReminder           |
| 🎯 **Productivity** | PomodoroTimer · FocusGuard · DailyStandup · DistractionBlocker |
| 💻 **System**     | DiskWatcher · BatteryGuard · NightShift · CpuCooler              |
| 🛠️ **Dev**        | GitReminder · BuildMonitor · PortWatcher · LogTailer             |
| 📊 **Data**       | ApiHealthCheck · CryptoTracker · WeatherAlert · RssDigest        |
| 📓 **Journal**    | MoodDiary · IdeaCapture · TimeTracker                            |
| 🔒 **Security**   | ScreenLocker · NetworkGuard · ClipboardCleaner                   |
| 📚 **Learning**   | WordOfTheDay · ReadingTimer                                      |
| 🤖 **Automation** | DownloadCleaner · BackupReminder · HomeLights                    |

Browse the full catalog on the [Explore page](https://openturtles.ai/explore).

---

## 📦 Releases

- **Current version:** `v0.12.0`
- **Install URL:** https://openturtles.ai/install.sh
- **All releases:** https://github.com/openturtles/cli/releases

---

## 🗺️ Roadmap & Status

All 15 foundational milestones (M1–M15) are **✅ complete** and shipped in `v0.12.0`.

<details>
<summary><strong>Milestone breakdown</strong></summary>

| Milestone  | Area                         | Highlights                                                                                  |
| :--------- | :--------------------------- | :------------------------------------------------------------------------------------------ |
| **M1–M4**  | Foundation                   | CLI, CRUD, Mission Compiler, QuickJS Executor, LLM Connector, Safety Guard, 32 JS APIs      |
| **M5–M5b** | Execution Engine             | Exponential backoff, caffeinate, JSONL logs, state persistence, loop detection, log rotation|
| **M6**     | Capability Extensions        | Home Assistant adapter, MCP client (stdio/SSE/HTTP), domain auto-discovery                  |
| **M7**     | Skill System                 | SKILL.md format, Skill Loader, 5-layer system prompt, ClawHub registry                      |
| **M8–M10** | Safety, Context, Learning    | Tool concurrency partitioning, context compression, observe→reflect→evolve adaptive learning|
| **M11**    | Community & Platform         | Homepage, Live Map, Explore, Dashboard, Docs, OAuth/OTP, JWT, Deploy Tokens                 |
| **M12–M15**| Daemon, Scheduling, DNA      | launchd/systemd auto-start, cron/at, event retention, server-side DNA compilation, versioning|

</details>

---

## 📖 Documentation

Full documentation lives at **https://openturtles.ai/docs**.

**🚀 Getting Started**
- [Installation](https://openturtles.ai/docs/install)
- [Quick Start (5 minutes)](https://openturtles.ai/docs/quickstart)
- [Deploy to OpenTurtles](https://openturtles.ai/docs/deploy-to-openturtles)

**📖 Core Concepts**
- [What is a Turtle?](https://openturtles.ai/docs/what-is-turtle)
- [Sentence → DNA → Execute](https://openturtles.ai/docs/sentence-dna-execute)
- [Observe → Reflect → Evolve](https://openturtles.ai/docs/observe-reflect-evolve)

**⌨️ CLI Reference**
- [`turtles create`](https://openturtles.ai/docs/turtles-create)
- [`turtles list` / `status`](https://openturtles.ai/docs/turtles-list)
- [`turtles start` / `stop` / `kill`](https://openturtles.ai/docs/turtles-lifecycle)
- [`turtles watch`](https://openturtles.ai/docs/turtles-watch)
- [`turtles connect`](https://openturtles.ai/docs/turtles-connect)
- [`turtles deploy` / `undeploy`](https://openturtles.ai/docs/turtles-deploy)
- [`turtles search` / `install`](https://openturtles.ai/docs/turtles-explore)

**🔌 Connect**
- [LLM Providers](https://openturtles.ai/docs/connect-llm) — Configure LLM servers for DNA compilation. Built-in support for OpenAI, Anthropic, Ollama (local), and any OpenAI-compatible endpoint (DeepSeek, Groq, Together…). Multi-server with one-command default switching.
- [MCP Servers](https://openturtles.ai/docs/connect-mcp) — Connect Model Context Protocol servers to extend Turtles with external tools — filesystems, databases, APIs, dev tools, and more. Supports `stdio`, `HTTP`, and `SSE` transports.
- [Skills](https://openturtles.ai/docs/connect-skill) — Markdown-based behavioral instructions (`SKILL.md`) that teach Turtles *how* to act, not just *what* to do. Install from a local directory or the ClawHub community registry.
- [Home Assistant](https://openturtles.ai/docs/connect-ha) — Let your Turtles control smart home devices — lights, sensors, climate, switches, media players. Multi-instance (e.g. home + office) with auto entity discovery.

**🐢 Use Cases**
[Health](https://openturtles.ai/docs/health) · [Productivity](https://openturtles.ai/docs/productivity) · [System](https://openturtles.ai/docs/system) · [Dev](https://openturtles.ai/docs/dev) · [Data](https://openturtles.ai/docs/data) · [Journal](https://openturtles.ai/docs/journal) · [Security](https://openturtles.ai/docs/security) · [Learning](https://openturtles.ai/docs/learning) · [Automation](https://openturtles.ai/docs/automation)

---

## 💬 Feedback & Support

We'd love to hear from you. Bug reports, feature requests, and product feedback are always welcome.

- 📮 **Feedback / Support** — feedback@openturtles.ai
- 🐦 **Twitter / X** — [@openturtles](https://twitter.com/openturtles)
- 🗺️ **Live Map** — https://openturtles.ai/live (see Turtles running around the world, city-level anonymized)
- 🐢 **Share your Turtle** — `turtles deploy <name>` — make it discoverable on the Explore page

---

## 📄 License

© 2026 OpenTurtles. All rights reserved.

OpenTurtles is a proprietary product. The `turtles` binary is provided free of charge for personal and commercial use, subject to the [Terms of Service](https://openturtles.ai/terms). Redistribution, reverse engineering, or derivative works are not permitted without prior written consent.

---

<div align="center">

**Our vision:** building the first **Global Reality AI Network** —
millions of Turtles, observing, acting, and evolving across the real world.

**Made with 🐢 by the OpenTurtles team.**

</div>
