ntn 0.4.5

Minimal AI coding agent powered by Claude Opus 4.7 (with adaptive thinking) or GPT-5.5

NTN - Minimal AI Coding Agent

A minimal AI agent that helps with coding tasks in a workspace. Supports multiple LLM providers (OpenAI GPT-5.5, Anthropic Claude).

Features

• Multi-provider support: Claude Opus 4.7 (default), Claude Sonnet 4.6, Claude Haiku 4.5, GPT-5.5
• Docker-first file operations: All file operations run in a Docker container with Unix tools
• Web search: Search using DuckDuckGo (ddgs package)
• Web fetching: Fetch and read webpage content
• Terminal execution: Run Windows commands when needed
• Persistent container: Single container per session, auto-starts on launch
• Command denylist: Dangerous commands require user confirmation
• Two-color tool display: Tool descriptions in yellow, paths in cyan for better readability
• Smart command detection: Recognizes common patterns (python -c, inline scripts) for better descriptions
• Colored output: Easy-to-read console with color-coded messages
• Debug logging: Incremental logging to debug/ folder (crash-resilient)
• Resume sessions: Continue previous conversations with -r flag
• Mid-turn resume: Automatically recovers from crashes mid-tool-execution
• Auto-compact: Automatically summarizes context when approaching token limit
• Auto-cleanup: Empty conversations (no user messages) are automatically deleted
• Rate limit handling: Automatically waits and retries using retry-after header
• Prompt caching: System prompt and tools are cached to reduce costs
• Model selection: Choose between Claude and GPT models with -m flag
• Streaming output: Real-time response display (always enabled)
• Cost tracking: Shows per-request and session costs with token usage
• Adaptive thinking: On Opus 4.7 / Sonnet 4.6, Claude dynamically decides when and how much to think (interleaved between tool calls). Default effort is max. Use -t off to disable, -e {low|medium|high|xhigh|max} to tune effort.

Installation

Install from PyPI:

pip install ntn

Or install from source:

git clone https://github.com/ntrnghia/coding-agent.git
cd ntn
pip install -e .

Setup

Set your API key based on the model you want to use:

For Claude models (default):

export ANTHROPIC_API_KEY='your-api-key-here'

For GPT-5.5:

export OPENAI_API_KEY='your-api-key-here'

(Optional) Install Docker for sandbox functionality.

Usage

Run the agent:

ntn

Resume a previous session:

# Resume most recent session
ntn -r

# Resume specific session
ntn -r debug/debug_20251210_120000.txt

Disable thinking (adaptive by default):

ntn -t off

Tune response effort (default max):

ntn -e high     # high effort (Anthropic API default when effort is omitted)
ntn -e medium   # balanced
ntn -e low      # fast / cheap
ntn -e xhigh    # extended capability for long-horizon work (Opus 4.7 only)
ntn -e max      # absolute maximum capability (default)

Per-model effort support: Opus 4.7 accepts all 5 levels. Sonnet 4.6 has no xhigh (it is auto-clamped to high). Haiku 4.5 ignores effort entirely. GPT-5.5 maps low/minimal → medium and max → xhigh. The CLI banner prints the value actually sent (e.g. effort: high (from xhigh)).

Use a different model:

ntn -m opus    # Use Claude Opus 4.7 (default)
ntn -m sonnet  # Use Claude Sonnet 4.6
ntn -m haiku   # Use Claude Haiku 4.5
ntn -m gpt     # Use GPT-5.5

Combine flags:

ntn -t off -r           # Resume with thinking disabled
ntn -m gpt -e medium    # GPT with medium effort

Alternative: Run as Python module:

python -m ntn

Input controls:

• Shift+Enter - New line (shows \)
• Enter - Submit message
• Ctrl+C - Exit the agent

Example prompts:

• "Create a new Python project with main.py and tests/"
• "Search for PyTorch distributed training docs"
• "List all Python files in this directory"
• "Run pytest on my tests"
• "Tell me what the code in D:\Downloads\some-project does" (uses Docker sandbox)

Package Structure

coding-agent/
├── src/ntn/
│   ├── __init__.py            # Package exports
│   ├── __main__.py            # Entry for `python -m ntn`
│   ├── _version.py            # Auto-generated version (from hatch_build.py)
│   ├── cli.py                 # CLI entry point and resume parser
│   ├── agent.py               # Main agent loop, compaction, cost tracking
│   ├── tools.py               # Tool implementations (Terminal, Web, Docker)
│   ├── tool_exec.py           # Tool execution + denylist confirmation
│   ├── providers.py           # LLM provider abstraction (Anthropic, OpenAI)
│   ├── provider_types.py      # Shared provider dataclasses (StreamEvent, etc.)
│   ├── stream_accumulator.py  # Normalizes streaming events into content blocks
│   ├── docker_manager.py      # Persistent Docker sandbox lifecycle
│   ├── session_log.py         # Incremental debug-log writer / parser
│   ├── prompts.py             # System prompt templates
│   ├── ui.py                  # Banner, status line, color helpers
│   ├── config.py              # Configuration loader (typed)
│   ├── config.yaml            # Configuration values (models, pricing, UI)
│   └── test_cache.py          # Local prompt-cache hit-rate tests
├── hatch_build.py             # Git-commit-count based versioning hook
├── pyproject.toml             # Package configuration
├── CHANGELOG.md               # Release notes
├── LICENSE                    # MIT License
└── README.md                  # This file

Tools

Terminal Tool

Executes shell commands in your workspace. Dangerous commands (rm, sudo, curl, etc.) require user confirmation before execution.

Web Search Tool

Searches the web using DuckDuckGo, returns top 10 results.

Fetch Web Tool

Fetches and extracts text content from URLs.

Docker Sandbox Tool

All file operations run in a Docker container for consistent Unix environment:

• Auto-starts on launch with workspace pre-mounted
• Single persistent container per session (named agent_<timestamp>)
• Directories mounted at Unix-style paths: D:\Downloads\project → /d/downloads/project
• Read-write access to all mounted directories
• Multiple directories can be mounted dynamically
• Container persists across prompts and survives resume
• Lazy recovery: If container stops, auto-restarts on next command
• Uses python:slim image by default

Context Management

The agent automatically manages context when approaching token limits:

1. Auto-compact triggers: Summarizes older conversation turns
2. Preserves current task: Summary includes your current question
3. Seamless continuation: You won't notice the compaction

Debug file shows compaction events:

=== COMPACTION EVENT ===
Reason: Exceeded context (180000 tokens attempted)
Removed turns: 1-3
Summary content: [condensed conversation]

Resume Sessions

Sessions are logged incrementally to debug/debug_<timestamp>.txt. To resume:

# Resume most recent session
ntn -r

# Resume specific session
ntn -r debug/debug_20251210_120000.txt

On resume:

• Previous conversation is displayed (including tool operations)
• Context is restored (including any compacted summaries)
• Container state is restored (mounts preserved)
• New messages append to the same debug file
• Crash recovery: If the agent crashed mid-turn, it will automatically continue from where it left off
• Multi-model support: Can resume with a different model than originally used

Debug Log Format

Debug files use an incremental format for crash resilience:

=== TURN 1 ===
--- USER ---
<user message>
--- ASSISTANT ---
<JSON response>
--- USAGE: {"model": "gpt", "input": 1000, "output": 50, ...} ---
--- TOOL_RESULT ---
<JSON tool results>
--- END_TURN ---

Each block is written immediately, so even if the agent crashes, the debug file contains all completed operations.

Output Format

The agent uses colored output for readability:

• 🟢 Green: Agent messages
• 🟡 Yellow: Tool descriptions (📂 List files, 📄 Read file, ✏️ Edit file, 🐳 Docker, etc.)
• 🔵 Cyan: Working directory paths (In /path/to/dir), system messages, user prompts
• 🟣 Magenta: Thinking indicator (🧠 Thinking: … — adaptive thinking enabled by default)
• 🔴 Red: Errors

Tool Display Example:

🐍 Run inline Python (In /d/downloads/coding-agent)
    ^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    Yellow           Cyan

Smart command detection automatically shows meaningful descriptions:

• python -c "..." → "🐍 Run inline Python"
• Long commands are truncated for readability

Full JSON input/output is logged to debug/debug_<timestamp>.txt for debugging.

Security Notes

• Commands run without timeout (for long-running processes)
• Dangerous commands require explicit user confirmation
• Docker sandbox provides isolated environment for external directories
• All commands run in the specified workspace directory
• Never commit API keys to version control

Multi-line input (Shift+Enter)

This CLI uses prompt-toolkit.

Important: Many terminals (including VS Code integrated terminal and Windows Terminal) do not pass a distinct Shift+Enter key event to terminal applications. To make Shift+Enter insert a newline reliably, configure your terminal to translate Shift+Enter into the sequence Esc then Enter (\u001b\r).

The CLI binds:

• Enter  submit
• Esc then Enter  insert newline

VS Code (Windows / PowerShell)

Add this to your VS Code keybindings.json:

{
  "key": "shift+enter",
  "command": "workbench.action.terminal.sendSequence",
  "args": {
    "text": "\u001b\r"
  },
  "when": "terminalFocus"
}

Windows Terminal (Windows / PowerShell)

In Windows Terminal settings.json, add an action that sends Esc+Enter and bind it to shift+enter.

Example (schema varies slightly by Windows Terminal version):

{
  "keys": "shift+enter",
  "command": {
    "action": "sendInput",
    "input": "\u001b\r"
  }
}

If you already created a sendInput action with an id, you can bind shift+enter to that action instead.