synk

A modular TypeScript developer agent for the terminal, built around the OODA loop (Observe ? Orient ? Decide ? Act), a Claude Code / OpenCode-style TUI, skill rulebooks, and AI providers that can be installed globally with npm install -g.

Setup

Requires Node.js 18+.

npm install          # install dependencies
npm run build        # compile TypeScript -> dist/
npm start            # run  (or: node dist/index.js [path])
npm run dev          # run from source with tsx
npm link             # optional: expose the `synk` command globally

synk                     # auto-detect the active file
synk src/app.ts          # target a file (or directory)
synk -t src/app.ts

Configuration and API keys live in ~/.synk/config.json (owner-only permissions; override the location with SYNK_HOME). Backups of every file Synk overwrites go to ~/.synk/backups/.

Using the REPL

Type / to open the command dropdown (?/? select, Tab completes, Enter runs).

| Command | What it does | | --- | --- | | /plan <objective> | Observes the target, maps/generates skills, outputs a roadmap. No files are changed. You can then execute, revise with feedback, edit it in $EDITOR, keep or discard it. | | /execute | Turns the approved plan into search/replace edits or full-file rewrites, shows a diff summary, asks for confirmation, backs up and writes. | | /skills [name] [input] | Menu of skills, or run name directly on the target with optional input. /skills new <name> drafts a skill. | | /configs | Arrow-key menu: switch provider (built-in or -g package), model, API key, endpoint; reload global providers. | | /models | Pick a model for the active provider. | | /target [path\|auto\|clear] | Set the active file/directory. | | /clear, /exit, /help | Clear screen + context, quit, list commands. |

Anything not starting with / is a normal chat message with the active target as context.

• Paste handling: pasting multi-line text (bracketed paste, or any multi-line burst) is captured as one payload shown as [Pasted text #1 +38 lines]; the full text is sent on Enter.
• Status footer: under the input � provider, model, target and token usage (prompt / eval).
• Ctrl+C cancels a running request; at the prompt press it twice (or Ctrl+D) to exit.

Skills

Skills are read only from .agents/skills/{skill_name}/SKILL.md in the working directory. If /plan decides a needed skill does not exist, or you run a skill that is missing, Synk drafts it with the active provider and saves it to .agents/skills/{missing_skill_name}/SKILL.md.

Providers

src/providers/interface.ts defines the AIProvider contract. Built in: Ollama and any OpenAI-compatible endpoint. Any package named synk-provider-* (or @scope/synk-provider-*) installed with npm install -g is discovered via npm root -g at startup (and on Reload in /configs). Extra search paths can be given with SYNK_PROVIDER_PATH.

A provider package default-exports an instance, a class, a factory function, or an array of them (provider, providers and createProvider named exports also work):

// synk-provider-example/index.js
module.exports = {
  id: 'example',
  name: 'Example AI',
  requiresApiKey: true,
  defaultModel: 'example-1',
  defaultBaseUrl: 'https://api.example.com',
  async listModels({ apiKey, baseUrl }) { return ['example-1']; },
  async chat(messages, { model, apiKey, baseUrl, temperature, signal, onToken }) {
    // call your API, stream pieces via onToken(text)
    return { content: '...', usage: { promptTokens: 12, evalTokens: 34 } };
  },
};

Packages written for the earlier stateful contract (initialize(config), getAvailableModels(), getDefaultModel(), chat(), optional streamChat(), configFields) are adapted automatically, e.g. synk-provider-ollama. A package may export a providers array to register several providers. A global package replaces a built-in with the same id. Provider-specific configFields appear under /configs ? Provider options.

Layout

src/index.ts          entry point / CLI args
src/providers/        interface.ts (contract), loader.ts (global -g loader), registry, built-ins
src/core/             agent (OODA), repl, commands, config (~/.synk), token tracker
src/skills/           scanner, mapper, autonomous generator
src/tools/            file-tools (sandboxed fs), code-writer (parse/preview/apply edits)
src/ui/               dashboard (banner), footer, input (raw-mode editor), slash-autocomplete, paste-handler, menus