arxivist CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is (read first)

arxivist is an AgentCulture mesh agent. Its stated domain (see pyproject.toml and README.md):

Agent + CLI that fetches arXiv papers, maintains a knowledge base, implements paper solutions, and benchmarks them against the papers' claims.

That domain is not built yet. The code currently in arxivist/ is the culture-agent-template scaffold — an agent-first introspection CLI (whoami, learn, explain, overview, doctor, cli) and nothing arXiv-specific. The runtime prose in README.md, arxivist/cli/_commands/learn.py, and arxivist/explain/catalog.py still literally describes the package as "a clonable template for AgentCulture mesh agents." When you build the real domain, you will be replacing that template prose, not adding alongside it.

So there are two distinct kinds of work here, and they call for different mindsets:

• Extending the agent — adding arXiv fetch / knowledge-base / implement / benchmark functionality. This is greenfield: add new noun groups following the existing CLI pattern (below) and retire the template framing as you go.
• Maintaining the scaffold — CI, skill re-syncs, version bumps, identity. The conventions below are load-bearing and enforced in CI; keep them green.

Commands

This is a uv-managed, Python 3.12+ package. The runtime has zero third-party dependencies (dependencies = [] in pyproject.toml) — keep it that way unless the domain genuinely requires a dependency, because the empty-deps property is part of the agent-first design. teken, pytest, lint tools, etc. are dev-only.

uv sync                                  # install deps + the package (editable)

# Tests
uv run pytest -n auto                     # full suite, parallel (what CI runs)
uv run pytest "tests/test_cli.py::test_whoami_text"   # a single test
uv run pytest -k whoami                    # tests matching a keyword
bash .claude/skills/run-tests/scripts/test.sh -p      # same, via the run-tests skill

# The CLI itself (two equivalent entry points)
uv run arxivist <verb> [--json]
uv run python -m arxivist <verb>

# Lint (CI's `lint` job runs all of these; line length is 100 everywhere)
uv run black --check arxivist tests
uv run isort --check-only arxivist tests
uv run flake8 arxivist tests
uv run bandit -c pyproject.toml -r arxivist
markdownlint-cli2 "**/*.md" "#node_modules" "#.local" "#.claude/skills" "#.teken"

# The agent-first rubric gate (CI's hardest gate — see below)
uv run teken cli doctor . --strict