{"id":"858d92a2-36f9-4a59-93d7-013bc04a5008","slug":"lordfoxfairy-nano-code","kind":"skill","name":"nano-code","summary":"nano-code","owner":"LordFoxFairy","repoUrl":"https://github.com/LordFoxFairy/nano-code","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-02-09T17:20:25.000Z","addedAt":"2026-10-22T02:20:57.755Z","logoUrl":"https://avatars.githubusercontent.com/u/34004635?u=bc651269dd4983b1a96ef90719e029ffa6865aae&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-24T04:01:07.381Z","sample":false,"url":"https://conduits.dev/tools/lordfoxfairy-nano-code","language":"TypeScript","transports":["stdio"],"install":{"npm":"nanocode"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# NanoCode\n\nA Claude Code-inspired AI-powered coding assistant built on the [deepagents](https://github.com/deepagents) framework. NanoCode provides an interactive CLI for software engineering tasks with comprehensive support for skills, subagents, hooks, plugins, and human-in-the-loop (HITL) workflows.\n\n## Features\n\n### Core Capabilities\n\n- **Multi-Model Support**: Works with Claude Opus, Sonnet, and Haiku via configurable providers (OpenRouter, Anthropic, etc.)\n- **Skills System**: Extensible skill definitions in `.agents/skills/` directories with dynamic arguments\n- **Subagents**: Define specialized agents for specific tasks\n- **HITL (Human-in-the-Loop)**: Approval workflow for file writes and command execution\n- **Tool Registry**: Centralized tool management with restriction support\n- **Session Management**: Save, restore, rename, and manage conversation sessions\n- **Streaming Responses**: Real-time response streaming with abort support\n\n### Advanced Features\n\n- **Hook System**: 9 event types for customizing agent behavior\n- **Plugin Architecture**: Extensible plugin system for custom functionality\n- **Permission Rules**: Fine-grained tool permission management (ask/allow/deny)\n- **Plan Mode**: Track and review proposed changes before execution\n- **MCP Integration**: Model Context Protocol support for external tools\n- **LSP Integration**: Language Server Protocol for code diagnostics\n- **Security Sandbox**: 50+ security patterns to block dangerous commands\n- **Middleware System**: Token tracking, cost calculation, and context summarization\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/thefoxfairy/nano-code.git\ncd nano-code\n\n# Install dependencies\nnpm install\n\n# Build\nnpm run build\n\n# Run\nnpm start\n\n# Or run directly with tsx\nnpm run dev\n```\n\n### Global Installation\n\n```bash\nnpm link\n\n# Now you can use it anywhere\nminicode\n```\n\n## Configuration\n\nCreate a `nano.config.json` file in your project root or home directory:\n\n```json\n{\n  \"providers\": [\n    {\n      \"name\": \"openrouter\",\n      \"baseUrl\": \"https://openrouter.ai/api/v1\",\n      \"apiKey\": \"YOUR_API_KEY\",\n      \"models\": [\n        \"anthropic/claude-opus-4\",\n        \"anthropic/claude-sonnet-4\",\n        \"anthropic/claude-3-haiku\"\n      ]\n    }\n  ],\n  \"router\": {\n    \"opus\": \"openrouter:anthropic/claude-opus-4\",\n    \"sonnet\": \"openrouter:anthropic/claude-sonnet-4\",\n    \"haiku\": \"openrouter:anthropic/claude-3-haiku\",\n    \"default\": \"openrouter:anthropic/claude-sonnet-4\"\n  },\n  \"settings\": {\n    \"defaultMode\": \"sonnet\",\n    \"interruptOn\": {\n      \"write_file\": true,\n      \"edit_file\": true,\n      \"execute\": true\n    },\n    \"streaming\": true\n  }\n}\n```\n\n## CLI Commands\n\n### Basic Commands\n\n```\n/help           Show available commands and skills\n/model [name]   Switch model (opus, sonnet, haiku)\n/clear          Clear conversation context (starts new thread)\n/exit           Exit NanoCode\n```\n\n### Session Management\n\n```\n/history [n]    Show conversation history (last n messages)\n/save [name]    Save current session with optional name\n/resume [id]    Resume a previous session (by ID or name)\n/rename <name>  Rename the current session\n/sessions       List all saved sessions\n```\n\n### Context & Status\n\n```\n/status         Show current session status\n/context        Show token usage visualization with cost estimate\n/compact        Summarize and compact context\n```\n\n### Skills & Tools\n\n```\n/skills         List all available skills\n/plugins        Manage installed plugins\n/permissions    Manage tool permission rules\n/keybindings    Show keyboard shortcuts\n```\n\n### Plan Mode\n\n```\n/plan           Enter/exit plan mode (track changes without executing)\n/plan:show      Show current proposed changes\n/plan:accept    Accept and execute all proposed changes\n/plan:reject [feedback]  Reject plan with optional feedback\n/plan:save [name]  Save current plan to disk\n/plan:load <id> Load a saved plan\n/plan:list      List all saved plans\n/plan:auto [on|off]  Toggle auto-accept mode\n```\n\n### Integration Commands\n\n```\n/mcp            Show MCP server status and available tools\n/mcp list       List all configured MCP servers\n/mcp tools      List all MCP-provided tools\n/mcp connect <server>    Connect to a specific server\n/mcp disconnect <server> Disconnect from a server\n\n/lsp            Show LSP server status\n/lsp start <lang>   Start language server (typescript, python, etc.)\n/lsp stop <lang>    Stop language server\n/lsp restart <lang> Restart language server\n/lsp supported      List supported languages\n```\n\n## Hook System\n\nNanoCode supports 9 event types for customizing agent behavior:\n\n| Event Type | Description |\n|------------|-------------|\n| `PreToolUse` | Before a tool is executed (can modify input or block) |\n| `PostToolUse` | After a tool completes (access to result) |\n| `UserPromptSubmit` | When user submits a prompt (can modify) |\n| `Stop` | When agent completes a response |\n| `SubagentStop` | When a subagent completes |\n| `SessionStart` | When a new session begins |\n| `SessionEnd` | When a session ends |\n| `PreCompact` | Before context is summarized |\n| `Notification` | For custom notifications |\n\n### Hook Configuration\n\nCreate a `hooks.json` file in your `.agents/` directory:\n\n```json\n{\n  \"description\": \"Project hooks configuration\",\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"./scripts/validate-tool.sh\",\n            \"timeout\": 5000,\n            \"description\": \"Validate tool inputs\"\n          }\n        ],\n        \"matcher\": \"Bash|Write\"\n      }\n    ],\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"echo 'Session started'\",\n            \"once\": true\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Hook Types\n\n- **Command hooks**: Execute shell commands with access to tool context via environment variables\n- **Prompt hooks**: Use LLM to process and respond to events\n\n## Plugin System\n\nPlugins extend NanoCode with custom skills, commands, agents, and hooks.\n\n### Plugin Structure\n\n```\nmy-plugin/\n  plugin.json       # Plugin manifest\n  skills/           # Custom skills\n  commands/         # Custom commands\n  agents/           # Custom subagents\n  hooks/            # Custom hooks\n```\n\n### Plugin Manifest (plugin.json)\n\n```json\n{\n  \"name\": \"my-plugin\",\n  \"version\": \"1.0.0\",\n  \"description\": \"My custom plugin\",\n  \"author\": \"Your Name\",\n  \"capabilities\": {\n    \"skills\": [\"my-skill\"],\n    \"commands\": [\"my-command\"],\n    \"hooks\": [\"my-hook\"]\n  }\n}\n```\n\n### Plugin Management\n\n```bash\n/plugins          # List installed plugins\n/plugins list     # Same as above\n```\n\n## Permission Rules\n\nControl tool access with fine-grained permission rules:\n\n### Permission Levels\n\n| Level | Description |\n|-------|-------------|\n| `allow` | Tool executes without confirmation |\n| `ask` | Requires user confirmation (default) |\n| `deny` | Tool is blocked |\n\n### Configuration\n\nCreate `~/.nanocode/permissions.json` for global rules or `.nanocode/permissions.json` for project-specific rules:\n\n```json\n{\n  \"rules\": [\n    {\n      \"tool\": \"Bash\",\n      \"arguments\": \"npm *\",\n      \"level\": \"allow\"\n    },\n    {\n      \"tool\": \"Write\",\n      \"arguments\": \"*.env*\",\n      \"level\": \"deny\"\n    },\n    {\n      \"tool\": \"*\",\n      \"level\": \"ask\"\n    }\n  ]\n}\n```\n\n### CLI Management\n\n```bash\n/permissions              # Show current rules\n/permissions list         # List all rules\n/permissions add <rule>   # Add a new rule\n/permissions remove <id>  # Remove a rule\n```\n\n## Plan Mode\n\nPlan mode allows you to review proposed changes before they're executed:\n\n```bash\n# Enter plan mode\n/plan\n\n# The agent will now record changes instead of executing them\n# You'll see: [Plan Mode] Recorded tool call: Write\n\n# Review proposed changes\n/plan:show\n\n# Accept all changes\n/plan:accept\n\n# Or reject with feedback\n/plan:reject \"Please don't modify the config file\"\n\n# Save plan for later\n/plan:save \"feature-refactor\"\n\n# Load a saved plan\n/plan:load abc123\n\n# Enable auto-accept\n/plan:auto on\n```\n\n## MCP Integration\n\nModel Context Protocol (MCP) enables integration with external tool servers.\n\n### Configuration\n\nCreate `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@my/mcp-server\"]\n    },\n    \"remote-server\": {\n      \"url\": \"https://my-mcp-server.example.com/sse\"\n    }\n  }\n}\n```\n\nOr in `~/.nanocode/mcp.json` for global configuration.\n\n## LSP Integration\n\nLanguage Server Protocol provides code intelligence features:\n\n### Supported Languages\n\n| Language | Server | Install |\n|----------|--------|---------|\n| TypeScript/JavaScript | typescript-language-server | `npm i -g typescript-language-server` |\n| Python | pylsp | `pip install python-lsp-server` |\n| Rust | rust-analyzer | Via rustup |\n| Go | gopls | `go install golang.org/x/tools/gopls@latest` |\n\n### Usage\n\n```bash\n/lsp start typescript   # Start TypeScript LSP\n/lsp                    # Check status\n```\n\n## Skills\n\nSkills are defined in `.agents/skills/` directories. Each skill has a `SKILL.md` file with YAML frontmatter:\n\n```markdown\n---\nname: my-skill\ndescription: A custom skill for specific tasks\n---\n\n# My Skill\n\nInstructions and knowledge for this skill...\n\n### /my-command\n\nThis is a command within the skill.\n```\n\n### Skill Commands\n\nCommands can be defined inline or in `commands/*.md`:\n\n```markdown\n---\ndescription: Run a specific action\nallowed-tools: Read, Write, Glob\nmodel: sonnet\nargument-hint: <file-path>\n---\n\nProcess the file at $1 and apply transformations.\n\nInclude content from @./config.json for reference.\n\nExecute: !`git status`\n```\n\n### Dynamic Arguments\n\n- `$1`, `$2`, `$3`... - Positional arguments\n- `$ARGUMENTS` - All arguments as a single string\n- `@filepath` - Include file contents\n- `` !`command` `` - Execute bash and include output\n\n## Subagents\n\nDefine subagents in `.agents/skills/*/agents/*.md`:\n\n```markdown\n---\nname: code-reviewer\ndescription: Reviews code for quality issues\nmodel: sonnet\ntools:\n  - Read\n  - Glob\n  - Grep\n---\n\nYou are a code review specialist. Analyze code for:\n- Code quality issues\n- Security vulnerabilities\n- Performance problems\n- Best practice violations\n```\n\n## Security\n\nNanoCode includes comprehensive security features:\n\n### Command Security\n\n50+ security patterns blocking dangerous operations:\n\n- **File Destruction**: `rm -rf /`, disk writes, filesystem formatting\n- **Privilege Escalation**: sudo exploits, SUID/SGID manipulation\n- **Network Attacks**: Reverse shells, firewall manipulation\n- **Sensitive Files**: SSH keys, AWS credentials, password files\n- **System Services**: Service manipulation, shutdown commands\n- **Crypto/Malware**: Mining software, ransomware patterns\n- **Code Injection**: Curl pipe to shell, eval injection\n- **Obfuscation**: Base64 decoding, hex payloads, Unicode evasion\n\n### Path Blacklist\n\nSystem directories protected from modification:\n\n```\n/, /bin, /sbin, /usr/bin, /usr/sbin, /etc, /boot,\n/sys, /proc, /dev, /root, /var/log, /var/run,\n/lib, /lib64, /usr/lib, /usr/lib64\n```\n\n### HITL Approval\n\nBy default, file writes and command execution require human approval.\n\n## Middleware\n\nNanoCode's middleware system provides:\n\n### Token Tracking\n\n```typescript\nimport { getUsageStats } from 'nano-code';\n\nconst stats = getUsageStats();\nconsole.log(`Total tokens: ${stats.totalTokens}`);\nconsole.log(`Estimated cost: $${stats.estimatedCost.toFixed(4)}`);\n```\n\n### Cost Calculation\n\nAutomatic cost calculation based on model pricing:\n\n| Model | Input (per 1M) | Output (per 1M) |\n|-------|----------------|-----------------|\n| Claude Sonnet 4 | $3.00 | $15.00 |\n| Claude Opus 4 | $15.00 | $75.00 |\n| Claude 3 Haiku | $0.25 | $1.25 |\n\n### Context Summarization\n\nAutomatic context compaction when approaching token limits:\n\n```typescript\nconst agent = await new AgentFactory({\n  config,\n  mode: 'sonnet',\n  cwd: process.cwd(),\n  summarization: {\n    maxTokens: 100000,\n    keepLastN: 10,\n  },\n}).build();\n```\n\n## Architecture\n\n```\nsrc/\n├── agent/              # Agent factory, tools, security\n│   ├── factory.ts      # Agent creation and configuration\n│   ├── tools.ts        # Custom NanoCode tools\n│   ├── security.ts     # Command security patterns (50+)\n│   ├── tool-registry.ts # Tool management\n│   └── sandbox.ts      # Local execution sandbox\n├── cli/                # CLI interface\n│   ├── ui/             # Ink-based UI components\n│   ├── commands.ts     # Slash command handling\n│   ├── plan-mode.ts    # Plan mode implementation\n│   ├── keybindings.ts  # Keyboard shortcuts\n│   └── session.ts      # Session management\n├── core/               # Core infrastructure\n│   ├── config/         # Configuration loading\n│   ├── llm/            # LLM model resolution\n│   ├── mcp/            # MCP integration\n│   ├── lsp/            # LSP integration\n│   └── agent/          # Agent/skill loaders\n├── hooks/              # Hook system\n│   ├── types.ts        # Hook type definitions\n│   ├── manager.ts      # Hook lifecycle management\n│   └── executor.ts     # Hook execution\n├── plugins/            # Plugin system\n│   ├── types.ts        # Plugin manifest schema\n│   ├── manager.ts      # Plugin lifecycle\n│   └── loader.ts       # Plugin discovery\n├── permissions/        # Permission rules\n│   ├── types.ts        # Permission types\n│   ├── rules.ts        # Rule matching\n│   └── manager.ts      # Rule management\n└── middleware/         # Middleware modules\n    ├── agent-middleware.ts  # Token/cost tracking\n    ├── tool-restriction.ts  # Tool access control\n    └── stop-validation.ts   # Stop condition checks\n```\n\n## API\n\n### AgentFactory\n\n```typescript\nimport { AgentFactory } from 'nano-code';\n\nconst agent = await new AgentFactory({\n  config,\n  mode: 'sonnet',\n  cwd: process.cwd(),\n  skills: ['.agents/skills/'],\n  hitl: true,\n  allowedTools: ['Read', 'Write', 'Glob'],\n  enableTokenTracking: true,\n  enableCostTracking: true,\n  onUsageUpdate: (stats) => {\n    console.log(`Cost: $${stats.estimatedCost.toFixed(4)}`);\n  },\n}).build();\n```\n\n### ToolRegistry\n\n```typescript\nimport { getGlobalToolRegistry } from 'nano-code';\n\nconst registry = getGlobalToolRegistry();\nregistry.register(myTool);\n\nconst { resolved, missing } = registry.resolveTools(['Read', 'Write']);\n```\n\n### Security\n\n```typescript\nimport { checkCommandSecurity, isDangerous, performSecurityCheck } from 'nano-code';\n\nconst result = checkCommandSecurity('rm -rf /');\n// { allowed: false, severity: 'block', category: 'file_destruction' }\n\nif (isDangerous(command)) {\n  throw new Error('Dangerous command blocked');\n}\n\n// Full check with paths\nconst fullResult = performSecurityCheck('cat /etc/shadow', ['/etc/shadow']);\n```\n\n### Permission Manager\n\n```typescript\nimport { getPermissionManager } from 'nano-code';\n\nconst manager = getPermissionManager();\n\n// Check permission\nconst level = manager.getPermission({\n  tool: 'Bash',\n  arguments: { command: 'npm install' }\n});\n\n// Add rules\nmanager.addGlobalRule({\n  tool: 'Write',\n  arguments: '*.ts',\n  level: 'allow'\n});\n```\n\n### Hook Manager\n\n```typescript\nimport { HookManager } from 'nano-code';\n\nconst hooks = new HookManager({ configPath: '.agents/hooks.json' });\n\n// Execute hooks\nconst result = await hooks.execute({\n  event: 'PreToolUse',\n  toolName: 'Bash',\n  toolInput: { command: 'npm test' },\n  context: { sessionId: '...', cwd: process.cwd() }\n});\n\nif (!result.continue) {\n  // Hook blocked the operation\n}\n```\n\n## Development\n\n```bash\n# Run tests\nnpm test\n\n# Run specific tests\nnpm test -- --run tests/unit/\n\n# Run with coverage\nnpm run test:coverage\n\n# Build\nnpm run build\n\n# Lint\nnpm run lint\n\n# Type check\nnpm run typecheck\n```\n\n## Testing\n\n511+ tests covering:\n\n- Unit tests for all modules\n- Integration tests for CLI and agent interaction\n- E2E tests for common workflows\n- Security pattern validation\n- Hook system tests\n- Plugin loading tests\n- Permission rule matching\n\n## Requirements\n\n- Node.js >= 18.0.0\n- npm or yarn\n\n## Dependencies\n\n- **deepagents**: Agent framework\n- **@langchain/anthropic**: Claude API integration\n- **@modelcontextprotocol/sdk**: MCP client\n- **ink**: Terminal UI components\n- **chalk**: Terminal styling\n- **zod**: Schema validation\n\n## License\n\nMIT\n\n## Credits\n\n- Built on [deepagents](https://github.com/deepagents) framework\n- Inspired by [Claude Code](https://claude.ai/claude-code)\n- Uses [LangChain](https://langchain.com/) and [LangGraph](https://langchain-ai.github.io/langgraph/)\n"}