Nekodex

Nekodex is a lightweight TypeScript agent CLI for working inside a local code workspace. It is built around a Codex-style terminal UI, persistent sessions, project instructions, memories, tool approvals, and OpenAI Responses models.

Highlights

• Codex-like React/Ink TUI with transcript history, bottom composer, slash commands, startup splash, model picker, approval prompts, and compact status line
• Auth with OpenAI API keys, ChatGPT browser login, or ChatGPT device-code login
• Workspace tools for listing files, reading files, writing files, text replacement, search, shell commands, and image generation
• Project and personal custom instructions from AGENTS.md, SKILL.md, .nekodex/instructions.md, Nekodex home, or NEKODEX_INSTRUCTIONS
• Persistent memories and resumable chat sessions
• Automatic context-window compaction for long sessions
• Configurable model, reasoning effort, approval mode, sandbox mode, sandbox backend, hosted OpenAI tools, and remote MCP servers
• Local stdio MCP server mode for exposing Nekodex workspace tools
• Linux, macOS, Windows, and Android Termux support

Install

pnpm add -g @mewbleh/nekodex

For local development:

pnpm install
pnpm build
pnpm start

Nekodex requires Node.js 22 or newer.

Login

Use an OpenAI API key:

nekodex auth login --api-key

Use a ChatGPT account in the browser:

nekodex auth login --chatgpt

Use device-code login when browser redirects are awkward, especially on SSH or Termux:

nekodex auth login --device-code

Check or clear auth:

nekodex auth status
nekodex auth logout

Start Chatting

Open the TUI in the current directory:

nekodex

Run a one-shot prompt:

nekodex -- "review the parser and add focused tests"

Use another workspace:

nekodex -C ../my-project

Use readline mode instead of the TUI:

nekodex --plain

When the TUI exits, Nekodex clears the terminal and prints the session id:

Nekodex session 4f3a8c91d21b
Resume with: nekodex resume 4f3a8c91d21b

Resume that session later:

nekodex resume 4f3a8c91d21b

TUI Commands

Inside the TUI, type / to open command suggestions.

/status          show auth, model, context, approval, sandbox, and instructions
/model           open the model picker
/model gpt-5.5   switch model immediately
/effort          open the reasoning-effort picker
/instructions    show loaded custom instruction files
/permissions     show approval and sandbox settings
/diff            show git status and diff summary
/compact         show context compaction settings
/clear           clear the visible transcript
/help            show all slash commands
/exit            quit

Keyboard basics:

Enter        send prompt or confirm a picker/approval
Esc          clear input, close overlays, or interrupt a running turn
Ctrl+C       interrupt a running turn; quit when idle
Tab          complete slash-command suggestions
Up/Down      move through slash suggestions and pickers
Left/Right   move the input cursor

Custom Instructions

Nekodex loads instructions before every agent turn. Use them for project rules, style preferences, verification commands, architecture notes, or reusable workflow guidance.

Project-level files:

AGENTS.md
AGENT.md
agent.md
agents.md
SKILL.md
skill.md
instructions.md
custom-instructions.md
.nekodex/AGENTS.md
.nekodex/AGENT.md
.nekodex/agent.md
.nekodex/SKILL.md
.nekodex/skill.md
.nekodex/instructions.md
.nekodex/custom-instructions.md

Personal files in the Nekodex config directory:

instructions.md
custom-instructions.md
AGENTS.md
agent.md

You can also point to one or more files explicitly:

NEKODEX_INSTRUCTIONS=/path/to/personal.md nekodex

Use the initializer for a clean project starter:

nekodex init

Inside the TUI, run:

/instructions

Memories

Memories are persistent notes injected into future turns.

nekodex memory add --title "Project style" "Use strict TypeScript and pnpm."
nekodex memory list
nekodex memory search typescript
nekodex memory remove <id>
nekodex memory clear

Model And Reasoning

Set defaults from the CLI:

nekodex config set model gpt-5.5
nekodex config set reasoningEffort medium

Override for one launch:

nekodex -m gpt-5.5 --effort high

Change inside the TUI:

/model
/model gpt-5.4-mini
/effort
/effort high

Tools And Approvals

By default, Nekodex asks before file writes and shell commands.

nekodex -y                         # approve automatically
nekodex --sandbox read-only        # inspect without writes
nekodex --sandbox workspace-write  # allow workspace writes
nekodex --danger-full-access       # allow outside-workspace access

Sandbox backends:

nekodex --sandbox-backend auto   # default; use bwrap when it is available and safe
nekodex --sandbox-backend node   # JS path checks only
nekodex --sandbox-backend bwrap  # require Linux bubblewrap
nekodex --sandbox-backend none   # no process sandbox backend

bwrap is only used for workspace-write shell commands. In auto mode it is attempted on Linux when Bubblewrap is installed and skipped on Termux, macOS, and Windows. File tools still use Nekodex path checks.

Configure hosted OpenAI tools:

nekodex tools add-openai web_search
nekodex tools add-openai image_generation --partial-images 2
nekodex tools list
nekodex tools clear-openai

Generate images from the local agent tool by asking in chat, for example:

create a 1024x1024 pixel-art icon for this CLI and save it in assets/

MCP

Add remote MCP servers for Responses API tool use:

nekodex mcp add docs https://example.com/mcp --auth-env DOCS_MCP_TOKEN
nekodex mcp list
nekodex mcp clear

Run Nekodex as a local stdio MCP server:

nekodex mcp serve -C .

Config

Nekodex stores local config in config.toml inside the Nekodex config directory. Existing config.json files are still readable as a fallback, but new writes go to TOML.

Inspect and edit local config:

nekodex config show
nekodex config set approvalMode ask
nekodex config set sandboxMode workspace-write
nekodex config set sandboxBackend auto
nekodex config set contextWindow.autoCompact true
nekodex config set contextWindow.compactThresholdTokens 200000

Example config.toml:

model = "gpt-5.5"
reasoning_effort = "medium"
approval_mode = "ask"
sandbox_mode = "workspace-write"
sandbox_backend = "auto"
allow_outside_workspace = false

[context_window]
auto_compact = true
compact_threshold_tokens = 200000

[[openai_hosted_tools]]
type = "web_search"

[[openai_hosted_tools]]
type = "image_generation"
partial_images = 2

[mcp_servers.docs]
url = "https://example.com/mcp"
bearer_token_env_var = "DOCS_MCP_TOKEN"
enabled_tools = ["search"]
require_approval = "never"

[mcp_servers.local]
command = "node"
args = ["server.js"]

Override the config directory with:

NEKODEX_HOME=/path/to/config nekodex

Platform Notes

Run diagnostics:

nekodex doctor

• Linux: install xdg-utils if browser login should auto-open.
• macOS: config defaults to ~/Library/Application Support/Nekodex.
• Windows: config defaults to %APPDATA%\Nekodex.
• Termux: install nodejs-lts; device-code login is the most reliable auth flow.