Metadata-Version: 2.4
Name: clawsome
Version: 2026.5.11
Summary: A lean Python harness for running persistent AI agents
Author-email: Jeff Froman <79345648+jefffroman@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/jefffroman/clawsome
Project-URL: Repository, https://github.com/jefffroman/clawsome
Project-URL: Issues, https://github.com/jefffroman/clawsome/issues
Project-URL: Changelog, https://github.com/jefffroman/clawsome/releases
Project-URL: Documentation, https://github.com/jefffroman/clawsome/blob/main/README.md
Keywords: ai,agents,claw,matrix,local-inference,persistent-agents,gateway,ollama
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matrix-nio[e2e]<0.27,>=0.25
Requires-Dist: httpx>=0.27
Requires-Dist: PyYAML>=6.0
Requires-Dist: apscheduler>=3.10
Requires-Dist: chromadb>=0.5
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: networkx>=3.2
Requires-Dist: markdown-it-py>=3
Requires-Dist: linkify-it-py>=2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

<img src="https://raw.githubusercontent.com/jefffroman/clawsome/2026.5.11/clawsome-logo.png" alt="Clawsome" width="80" align="left">

# Clawsome
A lean python harness for running persistent AI agents.

> Clawsome is under early, active development. Expect rough edges, breaking changes, and missing features. Feedback and contributions are welcome.

<br clear="left">


## Setup

Clawsome talks to a few external services (Ollama, SearXNG, a Matrix
homeserver) — get those running first, then `pip install -e .` and
point claw at a populated `claw.yaml`.

→ See [`docs/setup.md`](https://github.com/jefffroman/clawsome/blob/2026.5.11/docs/setup.md) for prerequisites, install notes
(including the macOS libolm wrinkle), and a first-boot checklist.

## Architecture

A single clawsome process manages **multiple agents**, each with a **workspace** (state on
disk) and **one or more channels** (inbound surfaces — Matrix is the shipped
one). Per-turn, the agent loads its transcript, assembles a system prompt
from injected identity files + retrieved memory, runs an Ollama tool loop,
and replies. Background tasks (compaction, memory_flush, reindex, cron,
session rotate) run **off** the user-reply path.

→ See [`docs/architecture.md`](https://github.com/jefffroman/clawsome/blob/2026.5.11/docs/architecture.md) for the full mental
model, request lifecycle, and workspace file contract.

## Configuration

`claw.yaml` is parsed once at startup; editing requires a restart. The
shipped `claw.example.yaml` is a runnable template with inline comments.

→ See [`docs/configuration.md`](https://github.com/jefffroman/clawsome/blob/2026.5.11/docs/configuration.md) for the full key-by-key
reference.

## Operations

Background tuning, daily session rotate, memory retrieval cadence, Matrix
bot first-deploy (token + cross-signing UIA + ghost-DM avoidance), and
log-based troubleshooting.

→ See [`docs/operations.md`](https://github.com/jefffroman/clawsome/blob/2026.5.11/docs/operations.md).

## Extending

Three extension points: **skills** (workspace-local; markdown protocol +
optional `tool.py`), **built-in tools** (in-tree; universal capability),
**channels** (in-tree; new inbound surface). Skills cover 99% of cases.

→ See [`docs/extending.md`](https://github.com/jefffroman/clawsome/blob/2026.5.11/docs/extending.md).

## Deployment

`pip install` exposes a `claw` console script that takes
`--config <path/to/claw.yaml>` and runs in the foreground. Wire it into
launchd / systemd / your process manager of choice as a long-lived service
running under a dedicated user. This repo intentionally does not ship
example service files — paths, log destinations, and label/unit names all
depend on the host layout.

---

## Contributing

Issues and pull requests are welcome on [GitHub](https://github.com/jefffroman/clawsome).
