Metadata-Version: 2.4
Name: stoat-linux
Version: 0.1.3
Summary: Safe local Linux operations engine with natural-language CLI workflows
Author-email: Yusuf Lawal <oneysl@outlook.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/initysl/stoat
Project-URL: Repository, https://github.com/initysl/stoat
Project-URL: Issues, https://github.com/initysl/stoat/issues
Keywords: assistant,linux,cli,automation,files
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click<9,>=8.1
Requires-Dist: rich<14,>=13.7
Requires-Dist: pydantic<3,>=2.5
Requires-Dist: toml<0.11,>=0.10.2
Provides-Extra: llm
Requires-Dist: ollama<0.7,>=0.6.1; extra == "llm"
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio<0.24,>=0.23; extra == "dev"
Requires-Dist: pytest-cov<5,>=4.1; extra == "dev"
Requires-Dist: black<25,>=24.1; extra == "dev"
Requires-Dist: ruff<0.3,>=0.2; extra == "dev"
Requires-Dist: mypy<2,>=1.8; extra == "dev"
Dynamic: license-file

# Stoat

**Safe local Linux operations engine** with a natural-language CLI.

Stoat turns short English requests into constrained local actions like finding files, moving/copying/deleting them safely, launching apps, undoing Stoat-managed changes, and showing recent history. It is terminal-first, Linux-only, and designed around confirmation, auditability, and reversible operations.

## Features

- Safe local file operations with confirmation, protected paths, and batch limits
- Natural-language file search with rule-based parsing
- Semantic file intents for categories like movies, pictures, documents, and screenshots
- App launch and close support for Linux desktop workflows
- Read-only system information for disk, memory, and battery status
- Undo and history for Stoat-managed reversible operations
- Pretty JSON output for scripting and future integrations
- Optional diagnostics with `stoat doctor`

## Quick Start

### Prerequisites

- Linux
- Python 3.11+

### Installation

```bash
# Install Stoat for normal use
pipx install stoat-linux
```

Optional LLM support is not required for the current rule-based product. If you want the optional parser backend later:

```bash
pipx install "stoat-linux[llm]"
```

### Usage

```bash
stoat run "open firefox"
stoat run "find my latest download"
stoat run "find all my movies"
stoat run --dry-run "move my latest screenshot to Desktop"
stoat run "copy all my movies to archive"
stoat run --dry-run "move report.pdf from Downloads to Documents"
stoat run "delete old.log from logs"
stoat run "delete the movie avengers"
stoat run "show disk usage"
stoat run "what's using my ram"
stoat history
stoat undo --yes
stoat doctor
```

### From Source

```bash
git clone https://github.com/initysl/stoat.git
cd stoat
uv sync --extra dev

# Run from the project environment while developing
uv run stoat run "find report"

# Optional local LLM support while developing
uv sync --extra dev --extra llm
```

## Documentation

- [Installation Guide](docs/installation.md)
- [Usage Examples](docs/examples.md)
- [Current Usage](docs/usage.md)
- [Execution Roadmap](docs/roadmap.md)
- [Configuration](docs/configuration.md)
- [Safety Features](docs/safety.md)
- [Release Process](docs/releasing.md)
- [Changelog](CHANGELOG.md)

## Development

```bash
uv sync --extra dev
uv run pytest -q
uv run ruff check stoat tests
uv run black --check stoat tests
uv run python -Im build --sdist --wheel --outdir dist
```

## License

MIT License - See [LICENSE](LICENSE) for details

## Contributing

Contributions welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) first.
