Skip to main content

nkd ("naked agents")

When you strip them down, AI agents are just LLMs running in loops with tools.

nkd is two things:

  1. A zero-abstraction async Python agent framework for Anthropic and OpenAI. Full type safety and direct control of SDK primitives, zero overhead.
  2. 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 as Unpack[...] of the provider SDK's own params TypedDict (e.g. Anthropic's MessageCreateParamsNonStreaming).
  • concurrency: tools in a turn run in parallel via asyncio.gather(). Tool context / deps just work via contextvars.
  • tool schemas: tool_schema(func) builds them from type hints and the docstring. Supports str, int, float, bool, Literal[...] (which also constrains generation to its choices).
    • schemas are always strict, every param required, so defaults raise. Need more? Pass the SDK's own tools=.
  • history: messages / input is mutated in place, atomically, after each full turn, so an interrupt never leaves an orphaned tool_use.
  • tracing: two OTel spans per GenAI semconv, invoke_agent and execute_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:
    • bash
    • read_file (text, images, PDF) · write_file · edit_file
    • fetch_url (saves page text via Playwright/Chrome) · web_search (DuckDuckGo via Playwright/Chrome)
    • models prefer bash; write_file/edit_file stay 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: enter send · ctrl+c quit · esc clear buffer / interrupt · tab cycle model · shift+tab cycle mode
    • backspace / option+backspace unbound 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 (default Act,Plan,Socratic); enough to shift behavior.
    • start phrase: NKD_START_PHRASE (default Be brief and exacting.); steers reliably over long contexts.
  • system prompt: ~/.claude/CLAUDE.md + ./CLAUDE.md.
  • config: env vars from the shell or ~/.claude/nkd/.env (shell values win): NKD_PROVIDER (anthropic or openai, default anthropic), the chosen provider's key (ANTHROPIC_API_KEY or OPENAI_API_KEY), NKD_LOG_LEVEL (default 20), plus NKD_MODES / NKD_START_PHRASE.

What I've deprecated, and why:

  • edit approval: clicking "yes" forever isn't oversight.
  • grep/glob tools: bash chains rg, 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)

Source distribution for nkd 1.0.0
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)

Table of built distributions (wheels) for nkd 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page