agentdir-cli 0.7.5__tar.gz

agentdir_cli-0.7.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentDir Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentdir_cli-0.7.5/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+include package.json
+recursive-include docs *.md
+recursive-include skills *.md
+recursive-include docs *.png
+recursive-include examples *.sh
+recursive-include scripts *.sh
+recursive-include tests *.py

agentdir_cli-0.7.5/PKG-INFO

@@ -0,0 +1,393 @@
+Metadata-Version: 2.4
+Name: agentdir-cli
+Version: 0.7.5
+Summary: Local-first Maildir-inspired work mailstore for software agents
+Author: AgentDir Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jstxn/agentdir
+Project-URL: Repository, https://github.com/jstxn/agentdir
+Project-URL: Issues, https://github.com/jstxn/agentdir/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development
+Classifier: Topic :: System :: Archiving
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: rich>=13.7
+Provides-Extra: watch
+Requires-Dist: watchfiles>=0.21; extra == "watch"
+Provides-Extra: semantic
+Requires-Dist: fastembed>=0.4; extra == "semantic"
+Requires-Dist: sqlite-vec>=0.1; extra == "semantic"
+Provides-Extra: team
+Requires-Dist: qdrant-client>=1.9; extra == "team"
+Requires-Dist: lancedb>=0.9; extra == "team"
+Requires-Dist: opentelemetry-api>=1.24; extra == "team"
+Requires-Dist: opentelemetry-sdk>=1.24; extra == "team"
+Dynamic: license-file
+
+# AgentDir
+
+<p align="center">
+  <img src="docs/assets/agentdir-overview.png" alt="AgentDir turns agent work into a saved trail, searchable memory, and proof for engineers." />
+</p>
+
+<p align="center">
+  <strong>Local-first memory and evidence for agentic engineering.</strong>
+</p>
+
+AgentDir is a flight recorder for coding agents. It lets agents record what
+happened during a software task, then gives engineers a clean way to inspect,
+replay, search, and audit that work later.
+
+The goal is simple: AgentDir should be nearly invisible while you work.
+
+Engineers should not have to manually start sessions, wrap commands, collect
+evidence, or maintain agent memory by hand. Once a repository is adopted, the
+agent operates AgentDir in the background and leaves behind a useful trail.
+
+## Why AgentDir Exists
+
+Agentic engineering has a trust gap.
+
+Agents can edit code, run tools, and summarize results, but their work often
+ends up scattered across chat history, terminal scrollback, temporary files, and
+unverified final claims. That makes it hard to answer basic questions:
+
+- What did the agent actually do?
+- Which commands support the final answer?
+- Were tests, builds, lint, or release checks really run?
+- What context did the agent retrieve and rely on?
+- Can a future agent learn from this session?
+- Can the index or memory layer be rebuilt if it breaks?
+
+AgentDir gives those answers a local, durable home.
+
+## What You Get
+
+| Capability | What it means |
+| --- | --- |
+| Invisible agent workflow | Agents run AgentDir commands during normal work, so engineers keep using their coding assistant normally. |
+| Evidence-backed claims | Test, build, lint, typecheck, doctor, and release claims can be checked against recorded tool results. |
+| Replayable sessions | Inspect the task, decisions, commands, outputs, blockers, summaries, and handoffs after the fact. |
+| Local-first storage | Records live in the repo-local `.agentdir` directory by default. No hosted service is required. |
+| Rebuildable memory | Raw event files are the source of truth. SQLite search and memory indexes can be rebuilt. |
+| Context lineage | Agents can emit context packs, then record which retrieved sources were consumed or cited. |
+| Cross-repo memory | Explicitly registered AgentDir roots can be searched together without moving canonical records. |
+| Secret-aware persistence | Common secret-like patterns are redacted before storage, with scan and cleanup commands for older records. |
+
+## The Invisible Workflow
+
+AgentDir is designed around a small separation of responsibility.
+
+| Human does | Agent does |
+| --- | --- |
+| Install AgentDir once. | Start and finish AgentDir sessions. |
+| Run `agentdir adopt` once per repo. | Capture evidence-bearing commands with `agentdir run`. |
+| Ask the coding agent to do work. | Record decisions, blockers, context, and handoffs. |
+| Inspect evidence only when needed. | Audit session quality and final claims before reporting. |
+
+In day-to-day use, the human workflow stays the same:
+
+```text
+Ask the agent to do the task.
+Review the result.
+Use AgentDir only when you want the trail.
+```
+
+The agent handles the recording surface:
+
+```bash
+agentdir work start "fix checkout failure" --emit-context
+agentdir run -- pytest -q
+agentdir audit session
+agentdir work finish --json
+```
+
+## Install
+
+Install from PyPI (the package is `agentdir-cli`; the command it installs is
+`agentdir`):
+
+```bash
+uv tool install agentdir-cli
+# or
+pipx install agentdir-cli
+```
+
+Or use the GitHub Release installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/install.sh | bash
+```
+
+The installer uses `pipx` when available. Otherwise it creates a self-contained
+virtual environment under `~/.local/share/agentdir` and links the CLI into
+`~/.local/bin`.
+
+Verify:
+
+```bash
+agentdir --version
+agentdir --help
+```
+
+## Pi Package
+
+Pi users can install this repository as a Pi package so the AgentDir skill is
+available automatically during coding tasks:
+
+Package page: [@jstxn/agentdir-pi](https://pi.dev/packages/@jstxn/agentdir-pi)
+
+```bash
+pi install npm:@jstxn/agentdir-pi@0.7.5
+# or install directly from a local checkout / release tag:
+pi install /absolute/path/to/agentdir
+pi install git:github.com/jstxn/agentdir@<tag-or-commit>
+```
+
+The package exposes `skills/agentdir/SKILL.md`; it teaches Pi to start AgentDir
+sessions, wrap evidence-bearing commands, use local memory/context packs, and
+produce evidence-aware handoffs. See [AgentDir Pi Package](docs/PI_PACKAGE.md)
+for details.
+
+## Adopt A Repository
+
+Run once from a git repository:
+
+```bash
+agentdir adopt
+```
+
+This is intentionally boring setup. It prepares the repository once, then agents
+operate AgentDir during normal coding work:
+
+- creates the repo-local `.agentdir` store
+- installs AgentDir-managed git hook shims
+- installs the Codex skill into the user skill directory
+- writes managed project guidance for common agent tools
+- asks interactive users whether `.agentdir/` should be added to the project or
+  user-level Git ignore file
+- runs `doctor` to confirm the store is healthy
+
+After that, agents have the guidance they need to use AgentDir without the
+engineer manually operating it during normal work.
+
+Preview setup without writing anything:
+
+```bash
+agentdir adopt --dry-run --json
+```
+
+If you want generated integration files to stay inside the AgentDir store
+instead of project instruction files:
+
+```bash
+agentdir adopt --install-skill store --install-generic store --integration-target store
+```
+
+For non-interactive installs, choose the ignore destination explicitly:
+
+```bash
+agentdir adopt --gitignore project  # write <repo>/.gitignore
+agentdir adopt --gitignore user     # write the user-level Git excludes file
+agentdir adopt --gitignore none     # leave ignore files unchanged
+```
+
+Undo managed setup while keeping the `.agentdir` evidence store:
+
+```bash
+agentdir unadopt          # dry-run
+agentdir unadopt --apply  # remove managed hooks and guidance
+```
+
+## What Gets Written
+
+Default adoption writes only local files:
+
+```text
+<repo>/.agentdir/                         # evidence, artifacts, indexes, state
+<repo>/.git/hooks/*                       # managed hook shims with backups
+<repo>/AGENTS.md                          # generic / Codex-readable guidance
+<repo>/CLAUDE.md                          # Claude Code guidance
+<repo>/.github/copilot-instructions.md    # Copilot guidance
+<repo>/.cursor/rules/agentdir.mdc         # Cursor guidance
+<repo>/.windsurf/rules/agentdir.md        # Windsurf guidance
+~/.codex/skills/agentdir/SKILL.md         # Codex skill, by default
+```
+
+Managed guidance is wrapped in AgentDir markers. Existing unmanaged content is
+preserved where the target format supports managed blocks.
+
+## Inspect A Session
+
+Most users will not need these commands every day, but they are the reason
+AgentDir exists.
+
+```bash
+agentdir status
+agentdir evidence --brief
+agentdir timeline
+agentdir report final --format json
+agentdir replay
+agentdir memory search "checkout failure"
+```
+
+For final-answer support:
+
+```bash
+agentdir audit session
+agentdir audit claims --text final-response.md
+```
+
+Audits are advisory by default. Use `--strict` when unsupported or contradicted
+claims should fail a check.
+
+## How AgentDir Works
+
+AgentDir has one source of truth and several rebuildable views:
+
+```text
+raw envelopes -> SQLite index -> memory/search/audit/report
+                    ^
+                    |
+             rebuilt from envelopes
+```
+
+1. **Raw envelopes**
+   Each meaningful event is stored as an immutable file in a Maildir-inspired
+   directory layout. These files are the source of truth.
+2. **Derived indexes**
+   SQLite indexes, search tables, memory passages, context packs, and audit
+   views are derived from the raw event files and can be rebuilt.
+
+Default project layout:
+
+```text
+<repo>/.agentdir/
+  sessions/
+  actors/
+  artifacts/
+  archives/
+  indexes/agentdir.sqlite3
+  state/
+  integrations/
+```
+
+The important property is recoverability: deleting the derived index does not
+destroy the session. AgentDir can rebuild from the envelope store.
+
+The agent-facing report surface is JSON. `agentdir report final --format json`
+and `agentdir work finish --json` include an `agent_handoff` object with
+verification evidence, failed evidence, claim support, context lineage, known
+gaps, and recommended next agent actions.
+
+## Unique Capabilities
+
+### Claims-To-Evidence Checks
+
+AgentDir can compare final-response claims such as "tests passed" or "build
+passed" against the latest recorded tool results. It does this with
+deterministic heuristics, not an LLM.
+
+Supported claim families:
+
+- test
+- lint
+- typecheck
+- build
+- doctor
+- release
+
+### Context Packs
+
+Agents can package retrieved context into auditable source manifests:
+
+```bash
+agentdir context build "checkout failure" --emit
+agentdir context consume --pack <pack-id> --source <source-id> --purpose plan
+agentdir context cite --pack <pack-id>
+agentdir audit context --pack <pack-id>
+```
+
+This does not prove a model paid attention, but it does make cooperative agent
+behavior visible.
+
+### Local Agent Memory
+
+AgentDir builds searchable local memory from prior sessions. Agents can search
+similar work, explain why a memory hit matched, and include relevant history in
+new context packs.
+
+```bash
+agentdir memory search "release evidence"
+agentdir memory explain "release evidence"
+agentdir context build "release evidence" --emit
+```
+
+Optional semantic extras exist, but the default path does not require a vector
+database or external embedding service.
+
+### Federated Memory
+
+For multi-repo work, AgentDir can search explicitly registered roots:
+
+```bash
+agentdir roots register ../other-repo --name other-repo
+agentdir memory search --federated "release evidence"
+```
+
+Each repository remains the canonical owner of its own `.agentdir` store.
+
+## Safety Model
+
+AgentDir is local-first and advisory by design.
+
+- It records what agents choose to record.
+- It does not replace code review or CI.
+- It does not send data to a hosted AgentDir service.
+- It treats raw envelopes as the source of truth.
+- It redacts common secret-like patterns before persistence.
+- It provides `secrets scan` and `secrets redact --apply` for cleanup.
+
+Useful commands:
+
+```bash
+agentdir doctor
+agentdir secrets scan
+agentdir secrets redact
+agentdir secrets redact --apply
+```
+
+## Upgrade And Rollback
+
+Upgrade an existing install and refresh current repo adoption:
+
+```bash
+agentdir --upgrade
+```
+
+Rollback to the previous stable release:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jstxn/agentdir/main/scripts/rollback.sh | bash
+```
+
+## Learn More
+
+- [Install Guide](docs/INSTALL.md)
+- [Agentic Coding Guide](docs/AGENTIC_CODING.md)
+- [Technical Brief](docs/TECH_BRIEF.md)
+- [Release Guide](docs/RELEASING.md)
+- [PRD](docs/PRD.md)
+
+## Project Status
+
+AgentDir is beta software for local-first agentic engineering workflows. The
+core model is stable: agents operate the recorder, engineers get the evidence,
+and raw local envelopes remain the recoverable source of truth.