nkd ("naked agents")
When you strip them down, AI agents are just LLMs running in loops with tools.
nkd is two things:
- A zero-abstraction async Python agent framework for Anthropic and OpenAI. Full type safety and direct control of SDK primitives, zero overhead.
- A Python terminal coding assistant built on it. I build production agents daily but used Claude Code as a black box. Building my own made me a producer, not a consumer: every interaction is a first-principles lesson in how agents work. It's now my primary workflow, fully shaped to how I think, and owning it lets me drop outdated habits like approving every edit.
The framework
pip install nkd
- thin wrapper:
agent()is just the basic loop: call the LLM; tool calls? run them, add results, repeat; none? return the text. - full type safety:
agent(**kwargs)is typed asUnpack[...]of the provider SDK's own paramsTypedDict(e.g. Anthropic'sMessageCreateParamsNonStreaming). - concurrency: tools in a turn run in parallel via
asyncio.gather(). Tool context / deps just work viacontextvars. - tool schemas:
tool_schema(func)builds them from type hints and the docstring. Supportsstr,int,float,bool,Literal[...](which also constrains generation to its choices).- schemas are always
strict, every paramrequired, so defaults raise. Need more? Pass the SDK's owntools=.
- schemas are always
- history:
messages/inputis mutated in place, atomically, after each full turn, so an interrupt never leaves an orphanedtool_use. - tracing: two OTel spans per GenAI semconv,
invoke_agentandexecute_tool. LLM calls are left to provider auto-instrumentation.
The CLI
curl -fsSL https://raw.githubusercontent.com/amitejmehta/nkd/main/install.sh | bash
Over time I've removed more than I've added. What remains:
- autonomy: full by default.
- tools:
bashread_file(text, images, PDF) ·write_file·edit_filefetch_url(saves page text via Playwright/Chrome) ·web_search(DuckDuckGo via Playwright/Chrome)- models prefer
bash;write_file/edit_filestay for the occasional colored diff.
- input:
tty.py, an async, tail-only raw-terminal handler (no cursor movement); every key is bound by the consumer. - keys:
entersend ·ctrl+cquit ·escclear buffer / interrupt ·tabcycle model ·shift+tabcycle modebackspace/option+backspaceunbound on purpose: I type faster, and the LLM reads typos fine.
- prefix: every message is sent as
CWD: <cwd> Mode: <mode>. <start phrase> <message>.- mode: a label from
NKD_MODES(defaultAct,Plan,Socratic); enough to shift behavior. - start phrase:
NKD_START_PHRASE(defaultBe brief and exacting.); steers reliably over long contexts.
- mode: a label from
- system prompt:
~/.claude/CLAUDE.md+./CLAUDE.md. - config: env vars from the shell or
~/.claude/nkd/.env(shell values win):NKD_PROVIDER(anthropicoropenai, defaultanthropic), the chosen provider's key (ANTHROPIC_API_KEYorOPENAI_API_KEY),NKD_LOG_LEVEL(default20), plusNKD_MODES/NKD_START_PHRASE.
What I've deprecated, and why:
- edit approval: clicking "yes" forever isn't oversight.
grep/globtools:bashchainsrg,find,ls, so one turn replaces several.- docker sandbox: rarely used, too many OS-level deps.
- thinking toggle: newer Claude models reject
disabled, and think judiciously anyway. - context management, all replaced by short sessions (below):
- cache warming (re-warmed Anthropic's 5 min cache each turn)
- saved history
- subagents (tool or headless)
- auto-compact (Haiku summarized history past a token limit)
What replaced them: kill sessions early and often. The artifact being edited (code, or the doc when writing) already holds most of the state. Anything else worth keeping (research, decisions) gets written down outside the session. Contexts stay small, so cache misses are cheap and the model stays sharp.
Metadata
Release files for nkd 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nkd-1.0.0.tar.gz | 37.6 kB | Without provenance | Details for nkd-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nkd-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for nkd-1.0.0-py3-none-any.whl |
Total release size: 55.5 kB
Release files / nkd-1.0.0.tar.gz
| Download URL | nkd-1.0.0.tar.gz |
|---|---|
| Size | 37.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0c0021bf54bdb8a573f4d5725a7cd868d326209a6c8c09fc96b99e388c95c56d
|
|
BLAKE2b-256 checksum How to use checksums |
15e294ff9b53c5b936f4d2df79025cd0e97b9f4e909f5b4b8dad88ae62fa7727
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / nkd-1.0.0-py3-none-any.whl
| Download URL | nkd-1.0.0-py3-none-any.whl |
|---|---|
| Size | 17.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8d8f266958088c76dc7440dfca029744f1eed468c793d64a94094af3615fea6b
|
|
BLAKE2b-256 checksum How to use checksums |
5d1512295cf652825c68c6394734c559a22aff30f03c5698a9061e1557d9900a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for nkd 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.