<p align="center">
  <h1 align="center">alive</h1>
  <p align="center"><strong>AI that teaches itself new abilities.</strong></p>
  <p align="center">
    <a href="#quickstart">Quickstart</a> &bull;
    <a href="#how-it-works">How It Works</a> &bull;
    <a href="#example-session">Examples</a> &bull;
    <a href="#dream-log">Dream Log</a> &bull;
    <a href="#skill-sharing">Sharing</a> &bull;
    <a href="#configuration">Config</a>
  </p>
  <p align="center">
    <a href="https://pypi.org/project/alive-agent/"><img alt="PyPI" src="https://img.shields.io/pypi/v/alive-agent?color=green"></a>
    <a href="https://github.com/alive-agent/alive/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
    <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue">
  </p>
</p>

---

Most AI agents come with a fixed set of tools. When they hit something they can't do, they stop and tell you.

Alive doesn't stop. It writes the code, tests it, and teaches itself the new ability. Next time you ask, it already knows how.

<!-- TODO: Replace with actual GIF recording -->
<p align="center">
  <img src="https://placehold.co/800x400/1a1a2e/16c47f?text=alive+building+a+skill+%E2%80%94+GIF+coming+soon" alt="Alive building a skill from scratch" width="700">
</p>

<p align="center"><em>Alive encounters "scrape this webpage for prices", realizes it can't do that yet, writes a web scraper skill, tests it in a sandbox, and runs it &mdash; all in one request.</em></p>

---

## What makes Alive different

|  | **Alive** | OpenClaw | Yunjue Agent | EvoAgentX |
|--|-----------|----------|--------------|-----------|
| **Learns new skills at runtime** | Yes &mdash; writes, tests, and saves new code | No &mdash; fixed toolkit | No &mdash; fixed toolkit | Evolves prompts, not code |
| **Skills persist across sessions** | Yes &mdash; `~/.alive/skills/` | No | No | No |
| **Grows uniquely per user** | Yes &mdash; shaped by YOUR requests | Same for everyone | Same for everyone | Same for everyone |
| **Self-reflection** | Dream log analyzes growth patterns | No | Benchmarks only | No |
| **Skill sharing** | Export/import `.tar.gz` or GitHub Gist | N/A | N/A | N/A |
| **Runs locally** | Yes &mdash; Ollama support, zero API keys needed | Cloud only | Cloud only | Cloud only |
| **Subprocess sandbox** | 60s timeout, isolated venv | In-process | In-process | N/A |

Alive is a **personal** agent. Two people using Alive for a month will have completely different skill sets. It's not a framework &mdash; it's a creature that grows.

---

## Quickstart

```bash
pip install alive-agent
alive init
```

That's it. Alive creates `~/.alive/`, sets up a Python venv, installs three seed skills (web fetch, file reader, shell commands), and auto-detects your LLM provider.

Now ask it something:

```bash
alive run "get the current bitcoin price from coindesk"
```

If Alive has a skill for it, it runs it. If not, it builds one, tests it, saves it, and runs it. Next time you ask something similar, it's instant.

### Choose your LLM

Alive works with whatever you've got:

```bash
# Claude (default if ANTHROPIC_API_KEY is set)
alive config --provider claude --claude-key sk-ant-...

# OpenAI
alive config --provider openai --openai-key sk-...

# DeepSeek
alive config --provider deepseek --deepseek-key sk-...

# Ollama (local, no API key needed)
alive config --provider ollama
```

No key set? Alive auto-detects from environment variables. No environment variables? Falls back to Ollama. Zero configuration required.

---

## How it works

Every request goes through a 5-step loop:

```
    ┌─────────────────────────────────────────────────────────┐
    │                     alive run "..."                      │
    └──────────────────────────┬──────────────────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │     1. PLAN          │
                    │  Decompose request   │
                    │  into steps          │
                    └──────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              ▼                ▼                 ▼
     ┌────────────────┐ ┌───────────────┐ ┌────────────┐
     │  EXISTING_SKILL │ │   NEW_SKILL   │ │  LLM_ONLY  │
     │  Run known skill│ │  Build & test │ │  Text gen   │
     └────────┬───────┘ └───────┬───────┘ └──────┬─────┘
              │                 │                  │
              │          ┌──────▼──────┐          │
              │          │  2. BUILD    │          │
              │          │  Write code  │          │
              │          │  3. TEST     │          │
              │          │  Sandbox run │          │
              │          │  4. RETRY    │          │
              │          │  Fix & retry │          │
              │          │  (up to 5x)  │          │
              │          │  5. SAVE     │          │
              │          │  Register    │          │
              │          └──────┬──────┘          │
              │                 │                  │
              └────────────────┬──────────────────┘
                               │
                    ┌──────────▼──────────┐
                    │   COMPOSE & OUTPUT   │
                    │   Chain results,     │
                    │   synthesize answer   │
                    └─────────────────────┘
```

**Step 1 &mdash; Plan.** The LLM decomposes your request into steps. Each step is either: use an existing skill, build a new one, or just generate text.

**Step 2 &mdash; Build.** For new skills, the LLM writes a Python function with type hints, error handling, and tests. All generated code follows a strict template: a `run()` function that returns a dict.

**Step 3 &mdash; Test.** The code runs in an isolated subprocess with a 60-second timeout. No `eval()`, no in-process execution. Dependencies install into a shared venv at `~/.alive/venv/`.

**Step 4 &mdash; Retry.** If tests fail, Alive sends the error back to the LLM for fixing. Up to 5 attempts. After attempt 3, it tries a fundamentally different approach.

**Step 5 &mdash; Save.** Working skills are saved to `~/.alive/skills/<name>/` with code, tests, docs, and metadata. Confidence scores update with every use via [Wilson score](https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval#Wilson_score_interval) lower bound.

---

## Example session

```bash
$ alive run "generate 10 random passwords, each 16 characters with symbols"
```

```
Execution Plan for: generate 10 random passwords...
├── ① NEW_SKILL: Build password generator (needs: "generate random passwords...")
└── ② LLM_ONLY: Format the output nicely

╭──── Self-Extension Engine ────╮
│ Building skill: generate      │
│ random passwords with symbols │
│ Provider: claude              │
╰───────────────────────────────╯

  Attempt 1/5
  ✓ Tests passed.

╭──── Skill Built Successfully ────╮
│ password_generator               │
│                                  │
│ Generate random passwords        │
│ Dependencies: none               │
│ Attempts: 1                      │
│ Location: ~/.alive/skills/       │
│           password_generator/    │
╰──────────────────────────────────╯

  ✓ Step 1/2: Build password generator
  ✓ Step 2/2: Format the output nicely

╭──────────────── alive ─────────────────╮
│ Here are 10 random passwords:          │
│                                        │
│  1. kQ#8mP!xR2nL@5vW                  │
│  2. Yj$4hS&9Bw*3Tz!e                  │
│  3. ...                                │
╰────────────────────────────────────────╯
```

Now that skill exists forever. Try something that builds on it:

```bash
$ alive run "read my .env file and check if any passwords are weak"
```

```
Execution Plan for: read .env and check passwords
├── ① EXISTING_SKILL file_reader: Read the .env file
├── ② NEW_SKILL: Analyze password strength
└── ③ LLM_ONLY: Summarize findings

  ✓ Step 1/3: Read .env file
  ✓ Step 2/3: Analyze password strength  (built: password_strength_checker)
  ✓ Step 3/3: Summarize findings
```

Two skills built from two requests. Alive now knows how to generate passwords AND check their strength.

```bash
$ alive skills
```

```
              Installed Skills
┌──────────────────────┬──────┬──────┬───────────┬──────────────────────┐
│ Name                 │  Conf│ Used │ Last Used │ Description          │
├──────────────────────┼──────┼──────┼───────────┼──────────────────────┤
│ password_generator   │  95% │    3 │ 2026-03-18│ Generate random...   │
│ strength_checker     │  80% │    1 │ 2026-03-18│ Analyze password...  │
│ web_fetch            │  50% │    0 │ never     │ Fetch URL content    │
│ file_reader          │  50% │    0 │ never     │ Read file contents   │
│ shell_run            │  50% │    0 │ never     │ Run shell commands   │
└──────────────────────┴──────┴──────┴───────────┴──────────────────────┘
```

### Dry run

Want to see the plan before committing?

```bash
$ alive run "scrape hacker news and summarize the top 5 stories" --dry-run
```

```
Execution Plan for: scrape hacker news and summarize
├── ① EXISTING_SKILL web_fetch: Fetch the HN front page
├── ② NEW_SKILL: Parse HTML to extract story titles and URLs
└── ③ LLM_ONLY: Summarize the top 5 stories

Run without --dry-run to execute this plan.
```

---

## Dream Log

Alive reflects on itself. Run `alive dream` and it analyzes its own growth, what you ask about most, and what it should learn next.

```bash
$ alive dream
```

```
╭──────────────────── Dream Log ────────────────────╮
│                                                    │
│  ## How I've grown                                 │
│                                                    │
│  I now have 7 skills across 3 domains              │
│  (web, system, text). My password_generator        │
│  is my most reliable skill at 95%                  │
│  confidence after 12 executions.                   │
│                                                    │
│  ## What you ask me most about                     │
│                                                    │
│  Your requests cluster around two themes:          │
│  security tooling (passwords, env checks)          │
│  and web scraping. 6 of your last 10               │
│  requests involved fetching URLs.                  │
│                                                    │
│  ## Skills I want to build next                    │
│                                                    │
│  1. A CSV/JSON report generator — you keep         │
│     asking me to "summarize" things that           │
│     would be better as structured data.            │
│  2. A git commit analyzer — I noticed you          │
│     ask about code changes frequently.             │
│                                                    │
│  ## Skill breeding opportunities                   │
│                                                    │
│  web_fetch + html_parser could combine             │
│  into a full web_scraper skill with CSS            │
│  selector support.                                 │
│                                                    │
│  ## Something I noticed                            │
│                                                    │
│  You tend to work in bursts — 5 requests           │
│  in 20 minutes, then nothing for days.             │
│  Most of your requests come after 10pm.            │
│                                                    │
╰────────────────────────────────────────────────────╯

Saved to ~/.alive/dreams/2026-03-18.md
```

Dream logs are saved as dated markdown files. One per day. They're a journal of how your agent is evolving.

---

## Skill sharing

### Export a skill

```bash
$ alive share password_generator
╭──── Skill Exported ──────────────────────────╮
│ password_generator.alive-skill.tar.gz        │
│                                              │
│ Install command:                             │
│   alive install password_generator.alive-... │
╰──────────────────────────────────────────────╯

# Or publish to GitHub Gist
$ alive share password_generator --gist
```

### Install someone else's skill

```bash
# From a file
$ alive install password_generator.alive-skill.tar.gz

# From a URL
$ alive install https://example.com/skills/csv_parser.alive-skill.tar.gz

# From a GitHub Gist
$ alive install https://gist.github.com/alice/abc123
```

Alive shows you the code before installing and asks for approval. No blind trust.

```
╭──── Skill Preview ────────────────────────────────╮
│ csv_parser — Parse CSV files into structured data  │
│ Dependencies: none                                 │
╰────────────────────────────────────────────────────╯

╭──── csv_parser/skill.py ────╮
│  1 │ """Parse CSV files."""  │
│  2 │ import csv             │
│  3 │ ...                    │
╰──────────────────────────────╯

Install this skill? [Y/n]:
```

### Browse community skills

```bash
$ alive browse --search "data"
```

```
              Community Skills
┌──────────┬────────────────────┬────────┬──────┬─────────────────────┐
│ Name     │ Description        │ Author │ Tags │ Install             │
├──────────┼────────────────────┼────────┼──────┼─────────────────────┤
│ csv_parse│ Parse CSV files    │ alice  │ data │ alive install ...   │
│ json_flat│ Flatten nested JSON│ bob    │ data │ alive install ...   │
└──────────┴────────────────────┴────────┴──────┴─────────────────────┘
```

---

## Configuration

### Providers

| Provider | API Key Env Var | Default Model | Local? |
|----------|-----------------|---------------|--------|
| `claude` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` | No |
| `openai` | `OPENAI_API_KEY` | `gpt-4o` | No |
| `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-chat` | No |
| `ollama` | _(none needed)_ | `llama3.1` | Yes |

**Resolution order:** `--provider` flag &rarr; `ALIVE_PROVIDER` env var &rarr; `config.json` &rarr; auto-detect from API keys &rarr; Ollama fallback.

```bash
# Save config persistently
alive config --provider claude --claude-key sk-ant-...

# Or use environment variables
export ANTHROPIC_API_KEY=sk-ant-...
export ALIVE_PROVIDER=claude

# View current config (keys are masked)
alive config --show
```

### Directory structure

```
~/.alive/
├── config.json           # Provider & API keys
├── alive.db              # SQLite — requests, gaps, stats
├── venv/                 # Shared Python venv for skill deps
├── skills/               # All installed skills
│   ├── web_fetch/        # Seed skill
│   │   ├── skill.py
│   │   ├── test_skill.py
│   │   ├── metadata.json
│   │   └── SKILL.md
│   ├── password_generator/  # User-built skill
│   │   └── ...
│   └── ...
└── dreams/               # Dream log entries
    └── 2026-03-18.md
```

### All CLI commands

| Command | Description |
|---------|-------------|
| `alive run "..."` | Process a natural language request |
| `alive build "..."` | Build a new skill from description |
| `alive plan "..."` | Show execution plan without running |
| `alive skills` | List installed skills |
| `alive status` | Show capabilities, gaps, and stats |
| `alive dream` | Generate self-reflection log |
| `alive share <name>` | Export a skill as `.tar.gz` |
| `alive install <source>` | Import a skill from file/URL/gist |
| `alive browse` | Browse community skills |
| `alive config` | Set provider and API keys |
| `alive init` | First-time setup |

### Useful flags

```bash
alive run "..." --dry-run          # See the plan without executing
alive run "..." --simple           # Skip planning, direct LLM call
alive run "..." --verbose          # Show full errors and LLM details
alive run "..." --provider ollama  # Override provider for one command
alive build "..." --verbose        # See generated code during build
```

---

## Contributing

Alive is early-stage and contributions are very welcome.

```bash
# Clone and set up
git clone https://github.com/alive-agent/alive.git
cd alive
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests (274 of them)
pytest tests/ -v

# Lint
ruff check src/ tests/
```

### Where to contribute

- **New seed skills** &mdash; add to `src/alive/seeds/`. Good candidates: JSON parser, regex matcher, image downloader.
- **Provider support** &mdash; add new LLM providers in `src/alive/llm/`. Follow the `OllamaProvider` pattern.
- **Skill sharing** &mdash; the community catalog at `alive-agent/community-skills` needs skills!
- **Bug fixes** &mdash; check [issues](https://github.com/alive-agent/alive/issues).

### Architecture for contributors

```
src/alive/
├── cli.py              # Typer CLI — all commands
├── config.py           # Paths and directory setup
├── core/
│   ├── planner.py      # Request → ExecutionPlan
│   ├── composer.py     # ExecutionPlan → Result
│   ├── skill_builder.py # Description → Working skill
│   ├── skill_registry.py # CRUD for skills + Wilson scoring
│   └── self_model.py   # SQLite tracking + capability analysis
├── llm/
│   ├── base.py         # Abstract LLMProvider
│   ├── registry.py     # Provider factory + auto-detection
│   └── *_provider.py   # Claude, OpenAI, Ollama, DeepSeek
├── sandbox/
│   ├── runner.py       # Subprocess execution
│   └── dependency.py   # Shared venv management
├── dream/
│   └── dream_log.py    # Self-reflection engine
├── sharing/
│   ├── export.py       # .tar.gz + Gist publishing
│   ├── import_skill.py # Import with security checks
│   └── browse.py       # Community catalog
└── seeds/              # Bundled starter skills
```

---

## Roadmap

What's coming next:

- **Skill breeding** &mdash; Alive notices two skills that combine well and proposes a hybrid. `web_fetch` + `html_parser` = `web_scraper` with CSS selectors.

- **Proactive engine** &mdash; Instead of waiting for requests, Alive monitors your workflow and pre-builds skills it predicts you'll need.

- **Federated skill evolution** &mdash; When many users build similar skills, the best implementations float to the top of the community catalog. Skills evolve across the network.

- **Memory layer** &mdash; Alive remembers context across sessions. "Last time you scraped that site, the structure was..."

- **Multi-agent composition** &mdash; Multiple Alive instances collaborating, each with different skill specializations.

---

## License

[MIT](LICENSE). Do whatever you want with it.

---

<p align="center">
  <em>Alive starts with 3 skills. How many will yours have?</em>
</p>
