winuxcode

A small TypeScript coding-agent MVP designed to sit between:

• ferryllm as the local LLM gateway
• winuxsh as the Windows-friendly shell execution layer

The MVP is intentionally small: a CLI agent loop, OpenAI-compatible chat-completions and Responses API clients, session persistence, transcripts, and a focused tool set for reading, searching, patching, writing, and running commands.

Setup

npm install
npm run build
npm run verify

npm run verify typechecks source and tests, runs the test suite, builds, and checks the built CLI help output.

Start ferryllm separately, then run:

set OPENAI_BASE_URL=http://127.0.0.1:3000/v1
set OPENAI_API_KEY=dummy
set WINUXCODE_MODEL=gpt-4o
npm run dev -- "inspect this project and suggest one improvement"

On PowerShell:

$env:OPENAI_BASE_URL = "http://127.0.0.1:3000/v1"
$env:OPENAI_API_KEY = "dummy"
$env:WINUXCODE_MODEL = "gpt-4o"
npm run dev -- "run typecheck and fix issues"

Agent runs print the selected approval policy, effective permission profile, configured shell tool mode, effective shell tool mode, enabled capability categories, workspace instruction load status/bytes, and run limits before the model turn starts. During the loop they print each tool call plus a compact tool result status and duration. Final run counters include total, succeeded, and failed tool calls plus LLM call count and duration totals.

Check local wiring without starting an agent turn:

npm run dev -- config-show
npm run dev -- --json config-show
npm run dev -- --version
npm run dev -- doctor
npm run dev -- --json doctor

config-show reports the selected workspace, resolved config, effective permission profile, shell tool mode, capability categories, enabled tool count/names, disabled tool count/names/reasons including --dry-run, whether a config file was loaded, and the loaded config file path when one was found. doctor includes a safety check with the resolved approval policy, effective permission profile, configured shell tool mode, effective shell tool mode, and capability categories including --dry-run, plus a git worktree check for the selected workspace. Text output ends with an ok, check-count, check-name, passed-check, failed-count, and failed-check-name summary; doctor --json includes the same top-level summary.

List enabled tools:

npm run dev -- tools
npm run dev -- --dry-run tools
npm run dev -- --json tools

tools reports the enabled tool count/names, disabled tool count/names/reasons, resolved permission profile, configured shell tool mode, effective shell tool mode, and enabled capability categories. tools --json includes the same metadata, top-level toolNames and disabledToolNames lists, structured disabled tool reasons, and the full tool definitions.

Inspect or clear persisted message history:

npm run dev -- session-info
npm run dev -- --json session-info
npm run dev -- session-clear

session-info reports existence, validity, byte-limit status, remaining byte/message capacity, byte/message-limit status, warning count, current runtime metadata, effective shell tool mode, and configured session byte/message limits in both text and JSON output, including malformed or oversized session files as valid: false so they can be inspected before clearing. JSON output includes saved metadata, message role counts, first/last message roles, and compatibility warnings. session-clear --json includes a deleted boolean.

Inspect transcript file state:

npm run dev -- transcript-info
npm run dev -- --json transcript-info
npm run dev -- transcript-clear

transcript-info reports existence, size, byte-limit status, remaining byte capacity, and text/JSON analyzed status. When the file is within transcriptMaxBytes, it also reports event count, event type counts/names, run-start count and last run-start safety/model metadata, step finish counts, last step finish reason/time, workspace instruction load count and last load status/bytes, max-tool-call limit hits and the last requested/max counts, tool call count/names/counts and last tool call step/name/time, tool result success/failure totals plus per-tool result names/counts, permission request count and last permission request details, transcript truncation count plus original-byte totals/max and the last truncation timestamp/bytes, last successful tool step/name/time/duration, last tool failure step/name/time/duration plus blocked-command permission request details when present, LLM failure count and last LLM failure step/time/duration, LLM duration totals/max/average, tool duration totals/max/average overall and per tool, first/last event timestamps, malformed JSONL line count, first malformed line number, and whether the analyzed JSONL is valid. Step-ended and LLM-failure transcript events include llmDurationMs when an LLM call was made. transcript-clear --json includes a deleted boolean.

Create winuxcode.config.json in the workspace:

npm run dev -- init
npm run dev -- --json init
npm run dev -- init --force

It writes winuxcode.config.json unless --config <path> is provided. init --json reports the created path and whether --force was used. It writes:

{
  "api": "chat",
  "approvalPolicy": "never",
  "permissionProfile": "workspace-write",
  "shellTool": "enabled",
  "baseUrl": "http://127.0.0.1:3000/v1",
  "apiKey": "dummy",
  "model": "gpt-4o",
  "shell": "winuxsh",
  "session": ".winuxcode/session.json",
  "transcript": ".winuxcode/transcript.jsonl",
  "maxSteps": 12,
  "maxToolCallsPerStep": 16,
  "llmTimeoutMs": 120000,
  "llmMaxRetries": 2,
  "shellTimeoutMs": 120000,
  "writeFileMaxBytes": 1048576,
  "patchMaxBytes": 1048576,
  "sessionMaxBytes": 5242880,
  "sessionMaxMessages": 400,
  "transcriptMaxBytes": 10485760,
  "transcriptMaxEventBytes": 1048576
}

CLI flags override environment variables, which override config file values.

Use "api": "responses" or --api responses to target ferryllm's /v1/responses endpoint. Use "approvalPolicy": "on-request", WINUXCODE_APPROVAL_POLICY=on-request, or --approval-policy on-request to opt into approval-request vocabulary for future interactive flows. The current MVP still refuses blocked commands. Use "permissionProfile": "read-only" or --permission-profile read-only to expose only read/search/git tools. --dry-run is a shortcut for read-only mode. Use "shellTool": "disabled", WINUXCODE_SHELL_TOOL=disabled, or --shell-tool disabled to keep write/patch tools while omitting run_shell. Use "session": ".winuxcode/session.json" or --session .winuxcode/session.json to persist message history across runs. Session files record the workspace, model, API mode, approval policy, permission profile, configured shell tool mode, and effective shell tool mode, and winuxcode warns when a resumed session differs from the current runtime. session-info shows the same metadata warnings without starting an agent turn. Use "transcript": ".winuxcode/transcript.jsonl" or --transcript .winuxcode/transcript.jsonl to capture session events. Transcript events include run-start safety/model metadata, workspace instruction load status/bytes, and tool result events include durationMs. Agent run outcomes include stepsUsed, handled toolCalls, llmCalls, LLM duration metadata, final messageCount, and stopReason for callers embedding the loop. CLI goal runs print the same counters and stop reason when the run stops. Use --no-session or --no-transcript to temporarily disable configured persistence for one run. Use "maxToolCallsPerStep" / --max-tool-calls-per-step to cap how many tools one assistant turn may request. Use "llmTimeoutMs" / --llm-timeout-ms and "llmMaxRetries" / --llm-max-retries to control LLM request timeout and retry behavior. Use "shell": "winuxsh", WINUXCODE_SHELL, or --shell powershell to choose the shell executable. Use "shellTimeoutMs" / --shell-timeout-ms to set the default and maximum timeout for run_shell. All built-in file, patch, git, and shell tool outputs include the workspace cwd. run_shell also includes the resolved timeout and output byte cap used for the command; timeout-limit rejections include requested and maximum timeout metadata. Use "writeFileMaxBytes" / --write-file-max-bytes to cap write_file content size. Use "patchMaxBytes" / --patch-max-bytes to cap apply_patch payload size. Use "sessionMaxBytes" / --session-max-bytes to cap session file load/save size. Use "sessionMaxMessages" / --session-max-messages to cap session history length. Use "transcriptMaxBytes" / --transcript-max-bytes to cap transcript file size. Use "transcriptMaxEventBytes" / --transcript-max-event-bytes to cap one transcript event.

Runtime numeric settings also have hard caps: 100 agent steps, 64 tool calls per assistant turn, 10 LLM retries, 10 minute LLM/shell timeouts, 10 MiB write/patch/transcript-event payload limits, 50 MiB session files, 100 MiB transcript files, and 2000 session messages.

Shell Integration

By default, shell commands run through winuxsh -c <command>. Override with:

$env:WINUXCODE_SHELL = "powershell"
npm run dev -- --shell powershell "run tests"

Safety

The MVP has explicit approval policy vocabulary and permission profiles, blocks obviously destructive shell commands, package dependency mutation commands across common JS/Rust/Go/.NET/Python package managers, file permission/attribute mutation commands, shell download-to-file commands, archive extraction commands, destructive git reset modes, branch-ref reset commands, tracked-file removal commands, destructive git merge/cherry-pick/revert commands, shell file copy/move commands, content-clearing/replacement/output commands, shell output redirection, scripts piped to shells, PowerShell encoded commands, PowerShell expression execution, history rewrite commands, low-level ref updates, recovery-history pruning commands, destructive worktree commands, and link creation commands, can disable the shell tool independently, caps shell command runtime, caps tool output and text-read limits, caps transcript events, redacts common secrets in diagnostics/session/transcript/tool output, keeps file tools inside the selected workspace, prevents read tools from reading dotenv files or protected .git and .winuxcode internals, and prevents write/patch tools from modifying those internals. File tool outputs also redact explicit secrets in returned path metadata. Tool output also redacts the configured API key as an explicit secret before it is returned to the model. Patches use unified diff or Codex-style patch envelope format and are applied by a small built-in patcher; patch outputs include patchBytes and maxPatchBytes, write outputs include maxBytes, and envelope outputs include changeCount. Moved patch outputs include both the new path and original from path. Blocked shell commands include a structured permissionRequest object with the active approval policy, command cwd, and matched safety pattern for a future approval UI, but the current MVP still refuses the command. The system prompt also steers the model toward dedicated file tools and away from dotenv files, protected workspace internals, shell dependency mutations, shell permission/attribute mutations, shell download-to-file commands, shell redirection, scripts piped to shells, PowerShell encoded commands, PowerShell expression execution, or destructive shell/git commands before the safety layer has to refuse them. Invalid tool inputs return structured validation issues plus issueCount. Unknown tool calls return redacted available tool names plus toolCount. list_files reports the effective glob pattern, ignored patterns, total, returned, limit, and truncation metadata. read_file reports selected/max line counts, maxBytes, and whether a line window was truncated before or after the returned content; oversized-file refusals include structured size metadata. search_text reports the effective glob pattern, limit, maxFileBytes, ignored patterns, file scan, skipped-file, and matched-line counts alongside returned matches. git_status returns both raw porcelain output plus maxOutputBytes and structured branch, entries, entryCount, stagedCount, unstagedCount, untrackedCount, renamedCount, and clean fields. Entries include the raw two-character code plus split index and worktree status fields. Branch metadata includes upstream plus ahead/behind counts when git reports them. git_diff returns raw diff output plus maxOutputBytes, changed, staged, path, fileCount, totalAdditions, totalDeletions, binaryFileCount, and per-file numstat metadata.

If the workspace has AGENTS.md files, winuxcode reads the root and nested files into the initial system prompt for new sessions.

MVP Shape

winuxcode CLI
  -> OpenAI-compatible HTTP clients
  -> ferryllm /v1/chat/completions or /v1/responses
  -> model/provider route

winuxcode tools
  -> list_files/read_file/search_text/git_status/git_diff/apply_patch/write_file
  -> run_shell through winuxsh -c
  -> JSONL transcript and JSON session store

Next useful upgrades:

• Add winuxsh --json -c support upstream so shell output is structured.
• Add streaming output for the Responses API client.
• Add approval policy/session-level accept controls.
• Keep expanding patcher and command safety behavior tests.

Reference analysis and porting notes live in docs/reference-notes.md.