@tyvm/knowhow

v0.0.130

Published

7 days ago

ai cli with plugins and agents

0High
0Medium
0Low

Knowhow CLI 🤖

Knowhow is an AI-powered CLI for generating docs, building embeddings for semantic search, and running interactive chat/agents—powered by a modular system of plugins, agents, and a secure worker that can expose your local tools to Knowhow Cloud.

📋 Table of Contents

🚀 Quickstart

Install

npm install -g @tyvm/knowhow

Initialize a project (`knowhow init`)

From your project directory:

knowhow init

This creates a local .knowhow/ workspace (config, prompts, generated docs, embeddings, language tooling, and a JWT placeholder) plus a global template directory in your home folder.

Login (`knowhow login`)

Knowhow authenticates to https://knowhow.tyvm.ai using browser-based OAuth (the CLI opens a browser, you approve, then it polls for approval and saves a JWT).

knowhow login

If you want to paste a token manually:

knowhow login --jwt

After login, Knowhow stores your JWT in .knowhow/.jwt and updates knowhow.json so models can route through the Knowhow proxy.

First steps after setup

Start the interactive chat:

knowhow chat

Or ask directly (no agent orchestration overhead):

knowhow ask --input "What should I work on next?"

You can also search embeddings:

knowhow search --input "How do plugins work in Knowhow?"

💬 knowhow chat

This is the primary way to use Knowhow. knowhow chat starts an interactive REPL-style loop where you type messages and use slash commands (/…) to control agents, renderers, search, sessions, and tools.

Tip: At startup, Knowhow prints a line like Commands: /agent, /agents, ...—use it to confirm which /… commands your build/config exposes.

Start a chat session

knowhow chat

Depending on your build, you may also see flags like selecting an initial agent, renderer, or enabling voice—check:

knowhow chat --help

Key slash commands (quick reference)

Agent switching

List configured agents:
```
/agents
```
Switch to an agent:
```
/agent <AgentName>
```
Example:
```
/agent Patcher
```

Multi-line input

/multi

Rendering control

/render basic
/render compact
/render fancy

Search (interactive)

/search

Inside /search, you’ll typically get sub-commands like:

next — show next result
exit — leave search
embeddings — list available embedding scopes
use — choose which embedding scope(s) to search

Sessions (attach / resume / logs)

List sessions:

/sessions
/sessions --completed
/sessions --completed --csv

Attach to a running task:
```
/attach
/attach <taskId>
```
Resume a completed/saved session:
```
/resume
/resume <taskId>
```
View recent attached logs:
```
/logs
/logs 50
```

Attached-mode controls (if your agent module supports them):

/pause
/unpause
/kill
/detach
/done

Shell commands (agent context via your machine)

Interactive shell (if enabled):
```
/!
```

Run command and send output to the AI:

/!! <command>

Example:

/!! cat ./build.log | tail -n 200

Voice (if available)

/voice

Switching agents (the “fast path”)

A typical workflow:

/agents
/agent Researcher
Summarize the pros/cons of using RAG vs fine-tuning...

⚙️ Configuration

Knowhow reads your project configuration from:

.knowhow/knowhow.json (local)
~/.knowhow/knowhow.json (global)

knowhow.json controls:

plugins (enabled/disabled)
sources (the docs generation pipeline)
embedSources (the embeddings pipeline)
model/agent wiring
worker settings and sandbox/security options
language tooling setup directory (.knowhow/language.json), etc.

Full reference: autodoc/config-reference.md

🔌 Plugins

Plugins are modular capability blocks that enrich agent sessions with:

additional context sources (files, URLs, GitHub/Jira/etc.)
semantic retrieval via embeddings
editor/session context (vim/tmux)
post-edit tooling (linter)
command execution for context (exec, powerful—use carefully)

Built-in plugins (by key)

language, vim, embeddings, github, git, asana, jira, linear, figma, notion, download, url, linter, tmux, agents-md, exec, skills

Full guide: autodoc/plugins-guide.md

⭐ Killer feature: Language Plugin (hotwords → injected context)

The Language Plugin lets you define hotwords/terms (in .knowhow/language.json). When you type a term like API or frontend, Knowhow automatically injects the relevant local files/text into your chat context.

Example (.knowhow/language.json):

{
  "API, apis, api documentation": {
    "sources": [
      { "kind": "file", "data": ["docs/api/**/*.md", "specs/openapi*.{json,yaml}"] },
      {
        "kind": "text",
        "data": "API answering guidelines:\n- include request/response notes\n- call out auth + errors\n- mention rate limits/pagination\n"
      }
    ]
  }
}

Then in chat:

Ask: What’s the contract for POST /sessions and what errors can it return?

If your term matches, the plugin injects your configured API docs automatically.

📚 Embeddings

Knowhow builds vector embeddings for semantic search.

Generate embeddings

knowhow embed

This runs over embedSources in knowhow.json and writes local embeddings JSON artifacts under paths like .knowhow/embeddings/.

Upload embeddings to Knowhow Cloud (or other backends)

knowhow upload

Supported flows (from embedSources.remoteType):

s3: uploads to s3://{bucketName}/{embeddingName}.json
knowhow: uses Knowhow API presigned URLs and syncs embedding metadata back to the backend (requires remoteId)

Download embeddings

knowhow download

Downloads embedding JSON artifacts into your configured embedSources[].output from:

s3, github, and knowhow (when remoteId is set)

Full guide: autodoc/embeddings-guide.md

📄 Generate Docs

Docs generation is driven entirely by your local config.sources pipeline in .knowhow/knowhow.json.

Run the generator

knowhow generate

High-level behavior:

expands sources[].input into matching files
resolves sources[].prompt from .knowhow/prompts/ (or uses prompt file / inline prompt)
writes results to sources[].output
skips unchanged inputs using hash-based caching tracked in .knowhow/.hashes.json

Full guide: autodoc/generate-guide.md

🔧 Worker System

The Knowhow worker is how you safely expose your local machine to AI agents running on knowhow.tyvm.ai.

It:

runs a local MCP-over-WebSocket server
connects to Knowhow Cloud
advertises only the tools you allow (via worker.allowedTools)
optionally runs tool execution in isolation (Docker sandbox) and/or requires passkeys to unlock

Start a worker

knowhow worker

Security model

Docker sandbox mode: run the worker in a Docker container for tool isolation (--sandbox or worker.sandbox: true)
Passkey-gated locked worker: when passkey auth is configured, the worker starts locked and blocks tool calls until you unlock using the passkey flow

Allowed tools (recommended flow)

On first run, if worker.allowedTools is missing, Knowhow auto-populates it from the available tool registry, writes it back into .knowhow/knowhow.json, and exits early so you can review/tighten your allowlist.

Share / unshare

knowhow worker --share / --unshare controls whether it’s visible to your organization (via request header)

Optional tunnel (config-driven)

When worker.tunnel.enabled === true, the worker may forward allowed ports to your local services for cloud-side reachability.

Full guide: autodoc/worker-guide.md

🧩 Extending Knowhow

Want more than the built-ins? Knowhow supports extension through modules and reusable instruction assets through skills.

Modules (tools, agents, plugins, commands)

Modules are dynamically loaded npm packages (or local files) that can register:

tools (tool-calling)
agents
plugins
commands (chat-loop extensions)
optional init() setup

Guide: autodoc/modules-guide.md

Skills (SKILL.md → injected instructions)

Skills are stored as SKILL.md files with frontmatter at the top (name, description). When your prompt contains a skill name (substring match), Knowhow injects the full SKILL.md content into the agent context.

Guide: autodoc/skills-guide.md

📖 CLI Reference

For command usage and behavior details, see: autodoc/cli-reference.md

🔗 Links

Website: https://knowhow.tyvm.ai
Twitter/X: https://x.com/micahriggan
npm: https://www.npmjs.com/package/@tyvm/knowhow

🚧 Dev & Nightly Releases

Knowhow publishes unstable/preview builds under separate npm dist-tags so that regular users on latest are never affected.

Installing a pre-release build

# Latest nightly (date-stamped)
npm install -g @tyvm/knowhow@nightly

# Latest dev snapshot (git-hash-stamped)
npm install -g @tyvm/knowhow@dev

# Pin a specific pre-release version
npm install -g @tyvm/[email protected]

How dist-tags work

| Tag | Installed by default? | Audience | |-----|-----------------------|---------| | latest | ✅ Yes (npm install @tyvm/knowhow) | All stable users | | nightly | ❌ No (must opt-in) | Testers / early adopters | | dev | ❌ No (must opt-in) | Developers / contributors |

Publishing a nightly or dev release never moves the latest tag, so existing users won't receive unstable code through normal updates.

Publishing scripts (for maintainers)

# Publish a date-stamped nightly (e.g. 0.0.108-nightly.20250428)
npm run publish:nightly

# Publish a git-hash-stamped dev snapshot (e.g. 0.0.108-dev.abc1234)
npm run publish:dev

# Publish a stable release to `latest`
npm version patch   # or minor / major
npm run publish:stable

Note: publish:nightly and publish:dev automatically version-bump the package.json with a pre-release suffix before publishing and do not create a git tag, keeping your git history clean.