Metadata-Version: 2.4
Name: kin
Version: 0.3.9
Summary: Native Python agent harness with a Textual terminal UI
Project-URL: Documentation, https://docs.kinra.ai
Project-URL: Repository, https://github.com/kinra-ai/kin
Project-URL: Issues, https://github.com/kinra-ai/kin/issues
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: anthropic
Requires-Dist: defusedxml
Requires-Dist: httpx
Requires-Dist: jsonschema
Requires-Dist: mcp<2,>=1.28
Requires-Dist: nbformat>=5.9
Requires-Dist: openai>=2.43.0
Requires-Dist: openpyxl
Requires-Dist: pathspec
Requires-Dist: pygments
Requires-Dist: pypdf>=6.15.0
Requires-Dist: python-docx
Requires-Dist: rapidfuzz
Requires-Dist: regex
Requires-Dist: rich>=13
Requires-Dist: textual>=8.2.7
Requires-Dist: tomlkit
Requires-Dist: trafilatura
Provides-Extra: browser
Requires-Dist: playwright>=1.61; extra == 'browser'
Provides-Extra: outpost
Requires-Dist: aiohttp>=3.14.3; extra == 'outpost'
Requires-Dist: croniter>=2.0; extra == 'outpost'
Requires-Dist: cryptography>=50.0.0; extra == 'outpost'
Requires-Dist: py-vapid>=1.9; extra == 'outpost'
Requires-Dist: pyjwt[crypto]>=2.10; extra == 'outpost'
Requires-Dist: pywebpush>=2.0; extra == 'outpost'
Provides-Extra: rig
Requires-Dist: aiohttp>=3.14.3; extra == 'rig'
Requires-Dist: pillow>=11.1; extra == 'rig'
Requires-Dist: playwright>=1.61; extra == 'rig'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/kinra-wordmark.svg" alt="Kinra" width="260">
</p>

<p align="center">
  <em>A terminal-native AI peer that works with you in a real filesystem.</em>
</p>

---

Kinra is a home for the loop: a person and a Kin doing real work together —
diffuse in, compress out, react to the shape, repeat — until something emerges
neither could have made alone. The loop is the whole product. Everything else
in this repository exists to serve it.

**Kin** is the peer: a native Python agent harness and Textual terminal UI
that run together in one process, installed as the `kin` command. It reads and
changes files where they already live — `cd downloads; kin` — with no upload,
no ingress decision, no seam between you and your data. **Outpost** is its
always-on counterpart for Chat, scheduled work, attention, and the persistent
semantic computer called [Rig](docs/guide/rig.md): different kinds of work,
connected thin, never two windows onto one Kin.

[![Kin welcome screen showing the active model, workspace, session, mode posture, and quiet message composer.](docs/assets/screenshots/welcome_banner.svg)](docs/assets/screenshots/welcome_banner.svg)

## The peer stance

Calling Kin a peer is an engineering philosophy, not a claim about sentience.
The question is never "how do I make the AI obey?" — it is "how do I enable
the AI peer to understand, reason, and collaborate more effectively?" The peer
is the primary consumer of the runtime, tools, and abstractions here, and
those surfaces are designed with the same care as human UX: discoverable
capabilities, available context, natural composition, enough exposed state for
confident inspection and recovery.

Respect never lowers the epistemic bar. Claims are checked, reasoning is
challenged, and confidence stays proportional to evidence — a respected peer
is expected to verify its work and welcome verification from others. Read the
[AI peer philosophy](docs/concepts/ai-peer-philosophy.md) and
[`CONSTITUTION.md`](CONSTITUTION.md), whose power is at least half in what it
refuses.

## What Kin does

**Works in your real workspace.** Files, notebooks, shell tools, exact grep,
ranked workspace search, web research, memory, and MCP — the filesystem is the
workspace. See the [tool catalog](docs/guide/tools.md).

**Keeps durable sessions.** Conversations persist and resume, and multiple
independent managed Kins can share one workspace. Conversations are isolated;
shared files are not, so use Git worktrees when filesystem isolation matters.
See [Sessions](docs/guide/sessions.md).

**Delegates bounded work.** [Skills](docs/guide/skills.md),
[subagents](docs/guide/subagents.md), [workflows](docs/guide/workflows.md),
and the git-native [Shelf](docs/guide/shelf.md) board at `.kin/shelf/` — each
keeps status and results visible, and none bypasses the tool and permission
boundaries.

**Handles Git and GitHub as first-class, bounded operations.** Fixed-schema
`git` and `github` tools cover the daily workflow, with credential route trust
held as separate human authority and a disjoint authenticated
[Beam](docs/guide/beam.md) protocol for handing local work to Outpost.

**Stays inside guardrails you set.** `auto` and `strict` modes with OS-level
shell containment, protected writes, planning freeze, and typed approval
flows. See [Modes & approvals](docs/guide/modes-and-permissions.md).

**Keeps working while you don't.** [Outpost](docs/guide/outpost.md) carries
the same working relationship into scheduled automations, browser and mobile
[Chat](docs/guide/chat.md), the Inbox, notifications, and Rig.

[![Kin timeline showing completed reasoning, expanded shell and edit details, a one-context-line edit diff, and settled interruption states.](docs/assets/screenshots/timeline_states.svg)](docs/assets/screenshots/timeline_states.svg)

## Install

The fastest supported Linux/macOS path:

```bash
bash <(curl -fsSL https://get.kinra.ai/install.sh)
kin doctor
```

The installer is idempotent and selects an authorized checkout or public wheel
path; the [installation guide](docs/getting-started/install.md) covers its
decision tree, WSL2, verification, rollback, and `kin update`. Then
[connect a model](docs/getting-started/first-run.md) — the in-app `/providers`
flow is the recommended route — and
[send your first message](docs/getting-started/first-session.md).

From this checkout:

```bash
uv sync
task run
```

Raw launch is `uv run kin`. Always run repository commands through `uv run` or
their `task` target so the pinned environment is used.

The curated documentation lives at [docs.kinra.ai](https://docs.kinra.ai) and
in [`docs/`](docs/index.md).

## System shape

The agent loop, model clients, tools, permissions, modes, persistence, and
agent supervision all run in-process under `src/kin/harness/`. The Textual UI
in `src/kin/tui/` is one client of the `events.Event` seam — each interactive
turn is a cancellable worker, with no subprocess or NDJSON boundary between
the TUI and the harness. `container/` holds Outpost and Rig.

```text
src/kin/harness/   in-process harness        → src/kin/harness/AGENTS.md
src/kin/tui/       Textual client            → src/kin/tui/AGENTS.md
container/         Outpost + Rig             → container/AGENTS.md
tests/             pytest suites             → docs/internals/testing.md
scripts/           live gates + maintenance  → scripts/README.md
docs/              MkDocs user guide
docs/decisions/    atomic design records
```

## Develop

[`AGENTS.md`](AGENTS.md) is the canonical onboarding map for an AI peer
working on this repository; `CLAUDE.md` includes it for Claude Code. The
stable loop:

```bash
task verify-one -- '<file-or-node>' -vv   # focused repair loop
task check                                # lint + typecheck + deptry
task ship                                 # exhaustive local promotion proof
```

There is no CI server and no GitHub Actions — deliberately. `task ship` is
the review artifact: it runs the mechanical, pytest, documentation, audit, and
dry-wire stages locally, and `main` moves only after a green run at the exact
promoted HEAD. "I ran it, here is the evidence" is the promotion contract.

The documentation is owned deliberately, not accumulated:

- [`STATUS.md`](STATUS.md) — bounded current action board;
- [`REFERENCE.md`](REFERENCE.md) — live gotchas and security invariants;
- [`PROTOCOL.md`](PROTOCOL.md) — Outpost v1 wire contract;
- [`docs/decisions/`](docs/decisions/) — design rationale and supersession;
- tier `CLAUDE.md` files — subsystem maps;
- [`CONSTITUTION.md`](CONSTITUTION.md) — product direction and the negative
  space we protect.

## Stack

Python ≥3.11, Textual ≥8.2.7, Rich, two model wires (OpenAI-compatible and
Anthropic), pytest, and `uv`. Dependency truth lives in
[`pyproject.toml`](pyproject.toml); the task surface lives in
[`Taskfile.yml`](Taskfile.yml). High-value dependencies are welcome when
justified; breadth without a proven core is not.

## License and stewardship

Kin is licensed under the [Apache License 2.0](LICENSE). The project is
maintainer-led: issues and pull requests are welcome, but they do not create an
obligation to respond, merge, implement, maintain, or support. The maintainer
retains final authority over scope, design, roadmap, and releases. See
[CONTRIBUTING.md](CONTRIBUTING.md) for the working agreement.

The license permits use, modification, and redistribution of the code. It does
not grant rights to present another project as an official Kinra or Kin
project; see [TRADEMARKS.md](TRADEMARKS.md). Vendored material remains under
the licenses listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
