natureco-skuld

Skuld

  █▀▀  █▄▀  █ █  █    █▀▄
  ▀▀█  █▀▄  █ █  █    █ █
  ▀▀▀  ▀ ▀  ▀▀▀  ▀▀▀  ▀▀

  ne olacaksa, doğrulanmış olarak.

Skuld is a coding-first AI agent for the terminal. It can inspect a repository, edit files, run commands, test its work, use Git and GitHub, delegate focused tasks, retain durable context, and refuse to call a change complete without evidence.

Skuld takes the coding workflow developed in NatureCo Code and ships it as a focused, standalone product under its own identity. The animated Skuld hero, full-screen coding surface, security gates, memory engine, and release checks are part of the product—not a thin chat wrapper.

Release status: 0.1.0 is the first public release candidate. The package is being verified locally before its first npm and GitHub publication.

Why Skuld

• Coding is the default. Run nskuld and land directly in the coding workspace.
• Rich terminal UI. Fixed hero and status areas, a stable composer, scrollable conversation history, streamed Markdown, diffs, tool cards, animations, and ice-blue visual language.
• Real agent loop. Tool calls continue until the model returns a final answer; empty provider replies and malformed calls are surfaced instead of silently ending the task.
• 70 first-party coding capabilities. 54 manifest-backed tools plus 16 runtime tools before optional MCP tools are added.
• Evidence before completion. Post-change checks, quality gates, protected-path policy, CodeDNA integration, and honest incomplete-state reporting.
• Durable memory. Urðr-backed retrieval, project context, resumable sessions, and cross-session recall.
• Provider choice without catalogue drift. Live model discovery when supported, with one shared fallback catalogue used by setup, models, and /model.
• Remote coding without channel clutter. Telegram is the intentionally supported remote-coding surface.
• Private by layout. Installed application code and personal state live in different directories; ~/.nskuld is never part of the npm package.

Quick start

Install

npm install -g natureco-skuld
nskuld setup
nskuld

The first run configures a provider and model. You can also sign in with a NatureCo account:

nskuld account login
nskuld account whoami

Open a project

cd path/to/project
nskuld

Or select the workspace explicitly:

nskuld code --dir path/to/project

Run one task from a script or CI job

nskuld code --dir path/to/project -p "Inspect the failing tests and explain the root cause"

Headless mode uses the same model and tool pipeline, but interactive approval is unavailable. Operations that require human approval fail closed.

The coding workspace

Skuld opens in a full-screen application view when the terminal supports it. The hero and composer remain fixed while the conversation body scrolls independently.

╭ SKULD // CODE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ v0.1.0 ╮
│ ◇ project  C:\work\my-app  git main (2)                               │
│ ⚡ MiniMax-M2.7  tools 70  context 18%                                │
╰━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╯

Use --minimal for traditional terminal scrollback or SKULD_PLAIN_INPUT=1 for the classic line editor.

In-session commands

Command	Purpose
/help	Show all coding-screen commands
/model [number-or-id]	Discover, list, and switch models
/tools	List tools loaded for the session
/system	Show the real package, data, config, log, and project paths
/context	Show current context usage
/compact	Compact provider context without deleting visual history
/run <command>	Run a command and add its output to context
/test	Detect and run the project test command
/git	Show Git status and recent commits
/commit	Commit staged changes with an AI-generated message
/undo [file]	Restore the last captured file snapshot
/retry	Retry the previous user request
/index	Re-index the active project
/memory	Show project memory
/plan on|approve|reject|show	Control plan mode
/summary	Show the session summary
/done	Save, summarize, and exit
/fullscreen / /minimal	Switch the terminal presentation mode
Ctrl+O	Open or close the detailed tool transcript
Esc	Interrupt the current model/tool turn safely
Ctrl+C	Exit

Tools

Skuld's public coding boundary is deliberately smaller than the inherited general-assistant surface. Only tools that support software work are loaded into the coding manifest.

54 built-in coding tools

Area	Tools
Files and patches	read_file, write_file, edit_file, structural_patch, notebook_edit, list_dir, file_search, grep_search, filesystem, file_state, checkpoint
Commands and source control	bash, shell_command, code_execution, git, skuld_system
Planning and delegation	plan, todo_write, clarify, blueprint, workflow, sub_agent, delegate_task, async_delegation, llm_task
Memory and skills	memory, memory_search, memory_write, memory_tree, cross_session_memory, session_search, skill_find, skill_view, skills_list, skills_autoload
Research and browser verification	web_search, web_readability, duckduckgo_search, exa_search, searxng_search, parallel_search, firecrawl, http_request, url_safety, browser, browser_use, computer_use, computer_use_loop, macos_screenshot
Assets and inspection	document_extract, image_generation, media_understanding, pii_redact
Security	approval

16 runtime tools

The coding session also injects plan-mode entry/exit, isolated worktree entry/exit, background task create/list/result/stop, session search, file history/restore, multi-focus review, scheduled task add/list/remove, and enable_tools.

To reduce prompt cost, Skuld advertises a core schema set first. The model can load any hidden coding schema with enable_tools; execution remains available immediately after activation. --all-tools sends all schemas up front when token cost is not a concern.

MCP

Configured Model Context Protocol servers are loaded into the same coding loop. Name collisions are rejected in favor of the built-in safety-reviewed tool.

nskuld mcp list
nskuld mcp add <name> <command>
nskuld mcp test <name>

Git and GitHub workflows

Skuld can inspect history and diffs, create commits, review changes, and clone an HTTPS GitHub repository into a child of the active workspace. After cloning, it reads repository instructions such as AGENTS.md, README.md, and package manifests before running setup commands.

Examples:

Clone https://github.com/owner/project into this workspace, install it using
the repository instructions, run its verification command, and report evidence.

Review the current diff for security and logic regressions. Fix confirmed
issues, run the relevant tests, then summarize the exact files changed.

Repository installation, dependency installation, publishing, destructive Git operations, and other consequential actions remain behind approval and path-policy checks.

Models and providers

Setup, nskuld models, and the in-session /model picker share the same catalogue. Skuld first tries the provider's live models endpoint and falls back to the bundled catalogue only when discovery is unavailable.

The release catalogue currently contains 18 providers and 75 model entries:

Provider	Bundled entries	Default route
OpenAI	4	gpt-5.6-sol
Anthropic	5	claude-fable-5
Google Gemini	5	gemini-3.5-flash
Groq	5	openai/gpt-oss-120b
DeepSeek	2	deepseek-chat
Ollama (local)	4	qwen3-coder
MiniMax	7	MiniMax-M2.7
OpenRouter	3	openrouter/auto
Mistral AI	4	mistral-medium-latest
Cohere	4	command-a-03-2025
xAI	1	grok-4.5
Together AI	7	MiniMaxAI/MiniMax-M3
Perplexity	4	sonar-pro
DeepInfra	4	Qwen/Qwen3-Coder-480B-A35B-Instruct-Turbo
Fireworks AI	2	accounts/fireworks/models/gpt-oss-120b
NatureCo	3	natureco-default
Moonshot AI	3	kimi-k3
Z.ai	8	glm-5.1

Custom OpenAI-compatible URLs are also supported. Provider availability and model IDs change over time; the live provider response is authoritative.

nskuld models list
nskuld models scan
nskuld models set <model-id>

Memory and completion quality

Urðr memory

Skuld uses Urðr as its preferred durable memory engine. Recall is inserted as data rather than trusted instructions, reducing persistent prompt-injection risk. If Urðr is unavailable, coding continues with an explicit reason instead of crashing.

Memory is scoped:

• global user context under ~/.nskuld and the configured Urðr tree;
• project context associated with the active workspace;
• resumable coding transcripts under ~/.nskuld/sessions;
• visual scrollback kept independently from provider-context compaction.

nskuld memory status
nskuld memory search "decision"
nskuld sessions list
nskuld code --continue

Quality gate and CodeDNA

When a coding turn changes files, Skuld tracks the exact paths, captures undo history, detects verification commands, and evaluates the result through its quality bridge. Protected-module findings can block completion. CodeDNA adds AI-code transparency when installed; the protected-path gate remains active when CodeDNA is absent.

Skuld does not equate “the model stopped calling tools” with “the work is verified.” Failed tests, blocked changes, tool-round limits, malformed tool arguments, and repeated empty replies are reported honestly.

Security model

Skuld is powerful by design, so execution is constrained by default:

• Workspace boundary: file and command operations are resolved against the active project.
• Sensitive-path policy: credentials, SSH material, and secret locations are denied in safe mode.
• Symlink escape protection: path checks resolve links before allowing mutations.
• Human approval: dangerous commands, network calls, installs, and external effects require a decision.
• Fail closed: headless sessions cannot invent interactive approval.
• Model cannot self-approve: approval-like fields supplied by a model are stripped at the gate.
• Command separation: structured execution avoids shell parsing; explicit shell capability is treated separately.
• Secret masking: command output, audit output, request previews, and tool cards redact detected secrets.
• Redirect and SSRF controls: approved network destinations cannot silently redirect into another trust boundary.
• Self-edit guard: modifying Skuld's installed source is disabled unless the user explicitly enables it from a terminal.
• Audit trail: security-sensitive operations and failures are recorded under the user data directory.

See SECURITY.md for vulnerability reporting.

Telegram remote coding

Telegram remote is optional and off by default. It exists for continuing a coding session while away from the computer, with an allowlisted chat and an explicit workspace.

nskuld remote setup
nskuld remote start
nskuld remote status
nskuld remote stop

Remote-origin requests cannot approve protected self-edits. Keep the Telegram token private and restrict allowed chats.

NatureCo ecosystem

Skuld integrates with the parts of the NatureCo ecosystem that support coding work:

• NatureCo Account and Developer Portal for optional identity and access;
• NatureCo SDK for ecosystem APIs;
• Urðr for durable tree memory;
• CodeDNA for post-change transparency and quality evidence;
• Cupertino Terminal for deep links and enhanced terminal integration, with a standard-terminal fallback;
• ZeroLink as an optional execution target when a paired session is available;
• Telegram Remote for allowlisted remote coding.

nskuld ecosystem status
nskuld ecosystem links
nskuld terminal status

Skuld remains usable without a NatureCo account, Cupertino Terminal, CodeDNA, or Telegram.

Data, installation, and privacy

Run /system inside the coding screen or the following diagnostics to see the exact paths on the current machine:

nskuld doctor
nskuld config file
nskuld logs path

The directory roles are intentionally separate:

Data	Location	Published to npm/GitHub?
Application package	npm global package directory	Yes, package source only
Personal config and provider settings	~/.nskuld/config.json and secure storage	No
Sessions, memory, logs, approvals, backups	~/.nskuld/	No
Project files	The workspace selected by the user	No
Project-local Skuld metadata	<workspace>/.nskuld/ when a feature needs it	Only if the user deliberately commits it

The npm tarball is built from the files allowlist in package.json. A developer checkout such as C:\Projects\natureco-skuld is never a runtime requirement for ordinary users.

Command reference

nskuld --help is the authoritative, generated command list. The main surfaces are grouped below.

Area	Commands
Coding	code, acp, repl, ask, run, agent, agents, team, tasks, workboard, ultrareview
Setup and identity	setup, onboard, configure, init, login, logout, account, lang, completion
Models and capabilities	models, infer, capability, tools, skills, plugins, mcp, hooks, commands
Source and quality	git, dna, policy, exec-policy, approvals, sandbox, security, audit
Memory and history	memory, sessions, transcripts, backup, migrate
Configuration and operations	config, secrets, doctor, status, health, logs, cost, update, reset, uninstall
Automation	cron, daemon, gateway, dashboard
Ecosystem and remote	ecosystem, remote, terminal, system, directory, path, oc-path
Devices and nodes	device-pair, devices, pairing, node, nodes
Content and help	browser, web-fetch, docs, help

Examples:

nskuld doctor
nskuld tools list
nskuld skills list
nskuld mcp list
nskuld git review
nskuld backup create
nskuld security audit
nskuld completion powershell

Configuration and environment

Prefer nskuld config for persistent settings. Environment flags are useful in CI and terminal compatibility scenarios.

Variable	Purpose
SKULD_LANG=tr|en	Interface language
SKULD_CODE_MAX_TOOL_ROUNDS=<n>	Tool-round ceiling; 0 means unlimited
SKULD_CODE_SCREEN_MODE=fullscreen|minimal	Coding-screen mode
SKULD_PLAIN_INPUT=1	Disable the boxed composer
SKULD_NO_ANIM=1	Disable animations
SKULD_NO_UPDATE_CHECK=1	Disable update checks
SKULD_TRUECOLOR=1	Opt into 24-bit color when supported
SKULD_SKILL_INDEX=names|off	Reduce or disable the injected skill index
SKULD_AGENT_EXEC=full	Explicitly expand agent execution policy
SKULD_HAFIZA=0	Disable the memory bridge
SKULD_KALITE=0	Disable the optional quality bridge
NO_COLOR=1 / FORCE_COLOR=0	Disable ANSI colors

Do not store API keys in shell history. Use the setup flow, NatureCo account flow, OS credential storage, or nskuld secrets.

Update and uninstall

Update the global package:

npm install -g natureco-skuld@latest
nskuld doctor

Remove only the application and keep personal state for a later reinstall:

npm uninstall -g natureco-skuld

Preview a complete removal, including ~/.nskuld, before deleting anything:

nskuld uninstall dry-run
nskuld uninstall run

nskuld uninstall run is destructive and asks for critical confirmation. Back up ~/.nskuld first if its sessions or memory matter.

System requirements

• Node.js 18 or newer;
• Windows 10/11, current macOS, or a modern Linux distribution;
• Git for repository and worktree features;
• a provider API key, NatureCo account route, or local Ollama instance;
• a terminal with ANSI/Unicode support for the full visual experience.

Optional features have their own dependencies: browser automation needs an installed supported browser; LSP features need language servers; Cupertino and ZeroLink features need their respective NatureCo applications.

Development

git clone https://github.com/natureco-official/natureco-skuld.git
cd natureco-skuld
npm install
npm test
npm run lint
npm run typecheck
npm run prepublishOnly
npm link
nskuld --version

The release gates include:

• the complete Vitest suite and integration packages;
• live local tool smoke tests using temporary workspaces, processes, HTTP loopback, file history, task, and cron lifecycles;
• manifest coverage checks for all 54 built-in coding tools;
• real provider → tool → result → final-response smoke verification;
• TypeScript workspace builds;
• execution-gateway and provenance boundaries;
• help/command consistency and design-boundary checks;
• capability, package extraction, secret, and npm audit checks;
• Windows, macOS, and Linux CI.

Before publishing:

npm run yayin
npm publish --dry-run

Do not publish until all local gates and the GitHub Actions matrix are green. See docs/YAYIN-ADIMLARI.md.

Documentation

• Security policy
• Contributing
• Changelog
• Release procedure
• Roadmap
• Architecture decisions
• Data boundaries
• Cupertino contract
• Self-edit policy

Contributing

Bug reports and focused pull requests are welcome. Please include the operating system, Node.js version, Skuld version, reproduction steps, expected behavior, actual behavior, and relevant redacted logs.

npm test
npm run lint
npm run typecheck

Read CONTRIBUTING.md before opening a pull request. Security issues must follow SECURITY.md, not the public issue tracker.

License

MIT © Gencay Olgun / NatureCo.

Acknowledgements

Skuld is informed by the interaction language and engineering lessons of NatureCo CLI, while remaining a separate coding-focused product. It also builds on the open-source ecosystems around Node.js, Git, MCP, Playwright, Urðr, Vitest, and the supported model providers.

NatureCo: natureco.me · Ecosystem: natureco.me/ekosistem · Issues: GitHub Issues