yazzang-homelabyazzang-homelab/im-looking-for/AGENTS.md

im-looking-for

AGENTS.md9 starsChanged 33 days agoMITView on GitHub

Guidance for AI coding agents (and people) changing im-looking-for. To use it from an agent, see docs/agents.md and skills/im-looking-for/SKILL.md. - One JSON shape per thing. Result.to_dict() and status.describe() are the contract for the CLI, the app's API and the MCP tools, documented in docs/agents.md (+ .ko.md). Change them together or not at all. - Pinned downloads. llama.cpp tag, model revision, sizes and SHA-256 live in assets.py. Changing the model or the prompts means bumping VECTOR_VERSION (embed.py) so old indexes are…

Installs packages

Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- docs/agents.mdAGENTS.md
- llms.txtllms.txt
- im-looking-forSkill

The file

We split this AGENTS.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
The media marker is per-run: read it from GET /props (media_marker).
line 27

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

AGENTS.md

Guidance for AI coding agents (and people) changing im-looking-for. To use it from an agent, see docs/agents.md and skills/im-looking-for/SKILL.md.

Layout

Path	What
`src/im_looking_for/cli.py`	`ilf` / `im-looking-for`: bare words search, subcommands, `--json`, exit codes
`src/im_looking_for/agent.py`	MCP server (`ilf mcp`) and the background index job shared with the app
`src/im_looking_for/web.py`, `static/index.html`	the app: loopback HTTP server + one page (setup wizard, folder browser, search, library)
`src/im_looking_for/engine.py`	index + llama-server lifecycle; the one object CLI, app and MCP use
`src/im_looking_for/indexer.py`, `extract.py`, `media.py`, `rules.py`	which files, read into segments, embedded
`src/im_looking_for/search.py`, `store.py`	scoring and the SQLite index (float16 vectors + FTS5 trigram)
`src/im_looking_for/assets.py`, `server.py`, `embed.py`	pinned llama.cpp + model downloads, the helper process, its HTTP API
`src/im_looking_for/status.py`	the status dict every surface reports
`tests/`	unit tests use `FakeEmbedder` (no model); `test_integration.py` needs the real model
`scripts/`	testbed + eval, screenshots (`shots.py`), PyInstaller entry

Rules

One JSON shape per thing. Result.to_dict() and status.describe() are the contract for the CLI, the app's API and the MCP tools, documented in docs/agents.md (+ .ko.md). Change them together or not at all.
Pinned downloads. llama.cpp tag, model revision, sizes and SHA-256 live in assets.py. Changing the model or the prompts means bumping VECTOR_VERSION (embed.py) so old indexes are rebuilt instead of mixed.
The media marker is per-run: read it from GET /props (media_marker); a fixed <__media__> breaks.
Read-only on user files. Nothing writes, moves or uploads user files. The app serves previews, passages and "open" only for paths already in the index, binds to 127.0.0.1, checks Host and a per-run token. Keep it that way.
stdout is for results. Progress goes to stderr, and only on a terminal; --json output must stay parseable.
Both languages. UI strings live in the T table in index.html (en, ko); docs come in *.md + *.ko.md. Korean docs use the formal written style (합니다체).
Measure claims. Speed, quality and score numbers in the docs come from real runs (scripts/eval.py, ilf ... --json); update them when they change, don't estimate.

Check

pip install -e ".[dev]"
pytest -q                                         # ~40 tests, no model needed
ruff check --line-length 120 src tests scripts    # remaining BLE001 etc. are deliberate
ILF_INTEGRATION=1 ILF_REAL_HOME=<data dir after `ilf setup`> pytest tests/test_integration.py
python scripts/eval.py scripts/testbed_eval.json  # needs the testbed (scripts/make_testbed.py) and the model

For UI changes, look at the result: python scripts/shots.py /tmp/shots --lang en (and --lang ko) drives the real app with Playwright and saves the main screens.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free