KnightCode Packages

KnightCode packages install and distribute extensions, skills, prompt templates, and themes as one unit. Use a package when a customization should be shared through npm or git, or when several resources belong together.

A package is an ordinary directory or npm package. It can expose conventional resource directories, declare explicit paths under the knightcode key in package.json, and carry its own runtime dependencies.

Install and manage packages

Install from npm, git, or a local path:

knightcode install npm:@example/knightcode-tools@1.0.0
knightcode install git:github.com/example/knightcode-tools@v1
knightcode install ./local-package

knightcode list shows configured packages. Use knightcode remove <source> to remove one and knightcode update --extensions to reconcile package installations. See Command Line for every package command and option.

If a configured package fails to install at startup, for example because npm cannot reach the registry, KnightCode warns about it, skips that package's resources, and keeps running. KnightCode tries to install it again on the next start or /reload. knightcode install and knightcode update --extensions still report the failure and exit non-zero.

Personal installs are written to ~/.knightcode/agent/settings.json. Add --local or -l to write the package declaration to .knightcode/settings.json. KnightCode reads declarations from that file only after project trust is granted.

Project packages are installed and loaded only after project trust is resolved. Packages can execute extension code and can include skills that instruct the model to run programs. Review third-party package source before installing it. Review project package declarations before granting project trust.

Use --extension or -e to try a package for one invocation without adding it to settings:

knightcode -e npm:@example/knightcode-tools

Choose a source

Versioned npm specifications are pinned. Git tags and commits are also pinned; package updates reconcile the checkout but do not move a configured ref.

Relative local paths resolve from the settings file that contains them. A file path loads one extension. A directory follows normal package discovery rules.

Create a package

The simplest package uses conventional directories:

my-knightcode-package/
├── package.json
├── extensions/
├── skills/
├── prompts/
└── themes/

Without a knightcode manifest, KnightCode discovers TypeScript and JavaScript extensions, skill directories, Markdown prompts, and JSON themes from those directories.

Use an explicit manifest when resources live elsewhere or need filtering:

{
  "name": "my-knightcode-package",
  "keywords": ["knightcode-package"],
  "knightcode": {
    "extensions": ["./src/extension.ts"],
    "skills": ["./resources/skills"],
    "prompts": ["./resources/prompts/*.md"],
    "themes": ["./resources/themes/*.json"]
  }
}

Paths are relative to the package root. Arrays accept glob patterns and exclusions. List dot-prefixed or symlinked resource roots directly when traversal through a glob would not discover them.

The knightcode-package keyword makes an npm package eligible for discovery in the KnightCode package gallery. Optional knightcode.image and knightcode.video fields add gallery previews.

Declare dependencies

Put runtime packages imported by extensions in dependencies. KnightCode installs package dependencies when it installs an npm or git source.

KnightCode supplies these packages to extensions and skills:

• @knightcode/ai
• @knightcode/agent
• @knightcodeai/cli
• @knightcode/tui
• typebox

Declare the host-provided packages listed above in peerDependencies with a "*" range and do not bundle them. KnightCode suppresses automatic peer installation for managed npm packages and git packages installed with npm, pnpm, or Bun. Local packages are not installed or modified, so their dependency tree remains the package author's responsibility.

Do not list host-provided packages in dependencies. A physical copy can bypass KnightCode's extension module mapping in compiled ESM and create duplicate classes, registries, and initialization work. KnightCode reports an extension warning when it detects this manifest configuration. Other KnightCode packages used as dependencies must be included in the published tarball and referenced through their node_modules resource paths.

Installed packages load with separate module roots. Do not rely on two packages sharing one dependency instance or one package resolving another package’s undeclared dependency.

Select package resources

The object form in settings narrows which resources load from a package:

{
  "packages": [
    {
      "source": "npm:@example/knightcode-tools",
      "extensions": ["extensions/*.ts", "!extensions/legacy.ts"],
      "skills": [],
      "prompts": ["prompts/review.md"]
    }
  ]
}

For each resource type:

• Omit the property to load everything allowed by the package.
• Use [] to load none of that type.
• Use !pattern to exclude glob matches.
• Use +path to include one exact allowed path.
• Use -path to exclude one exact path.

Filters narrow the package manifest. They do not expose resources that the package itself did not declare.

Run knightcode config to enable or disable discovered resources and knightcode's built-in extensions. It starts with personal configuration; press Tab to switch scope, or run knightcode config --local to start with project overrides.

Understand scope and identity

The same package can appear in personal and project settings. A project entry normally replaces the personal entry. With autoload: false, the project entry instead acts as a filtering delta over the personal package.

KnightCode identifies npm packages by package name, git packages by repository URL without the ref, and local packages by resolved absolute path. This prevents the same package from loading twice through equivalent declarations.

Use Extensions, Skills, Prompt Templates, and Themes to design each resource before packaging it.