Quickstart

git clone [email protected]:kingkillery/pk-agent.git && cd pk-agent && bun install && bun run build && npm pack && npm install -g ./pk-agent-*.tgz

What is PK-Agent?

PK-Agent lets you create AI-powered assistants by writing a short text file - no programming needed. Each file is a set of instructions that tells an AI model what to do, like giving directions to a very capable coworker.

Think of it like a recipe card. The top section lists the ingredients (which AI model to use, what tools it needs). The bottom section is the actual instructions - written in plain English.

Here's a complete agent that generates a daily motivation quote:

---
model: anthropic:claude-sonnet-4-5
---

Generate a daily motivation quote with a tech fact.
Format as JSON with 'quote' and 'fact' fields.

That's it. That file is the agent.

Getting Started

1. Install

Open a terminal (Command Prompt, PowerShell, or Terminal) and run:

npm install -g pk-agent

2. Connect your AI provider

PK-Agent needs an API key from an AI provider. Think of this like a password that lets PK-Agent talk to the AI on your behalf.

pk-agent auth login

This walks you through connecting to Anthropic (Claude), OpenAI (GPT), or other providers.

3. Create your first agent

Recommended: generate a starter agent file with:

pk-agent create

Or create one manually:

Create a new text file called my-agent.pk-agent and paste this in:

---
model: anthropic:claude-sonnet-4-5
---

You are a friendly assistant. Greet the user, tell them one
interesting fact about space, and wish them a great day.

4. Run it

pk-agent run my-agent.pk-agent

You'll see the AI respond right in your terminal.

Tip: You can also try agents without installing anything:

npx pk-agent@latest run my-agent.pk-agent

How Agent Files Work

Every .pk-agent file has two parts:

---
model: anthropic:claude-sonnet-4-5     # Settings (YAML)
---

You are a helpful research assistant.  # Instructions (Markdown)
Summarize the latest news about AI
and format it as bullet points.

| Part | What it does | Required? | |---|---|---| | Settings (between --- lines) | Tells PK-Agent which AI model to use and what tools to provide | Yes | | Instructions (below the settings) | Tells the AI what to do, in plain English | Yes |

Choosing a model

The model line tells PK-Agent which AI to use. Some popular options:

| Model | Best for | |---|---| | anthropic:claude-sonnet-4-5 | General tasks, writing, analysis | | openai:gpt-5.2 | Broad knowledge, conversation | | openai:gpt-5.2-mini | Fast, lightweight tasks |

You can switch models by changing one line - your instructions stay the same.

Real-World Examples

Summarize a webpage

---
model: anthropic:claude-sonnet-4-5
mcpServers:
  fetch:
    command: uvx
    args: [mcp-server-fetch]
---

Fetch https://news.ycombinator.com and summarize the top 5 stories
in plain language. Keep each summary to 2 sentences.

Monitor a website for changes

---
model: anthropic:claude-sonnet-4-5
schedule: "0 9 * * *"
mcpServers:
  fetch:
    command: uvx
    args: [mcp-server-fetch]
---

Fetch https://example.com/changelog and compare it to yesterday.
If anything changed, write a summary of what's new.

The schedule line tells PK-Agent to run this automatically. "0 9 * * *" means "every day at 9:00 AM."

Query a database and write a report

---
model: anthropic:claude-sonnet-4-5
mcpServers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    requiredEnvVars: [DATABASE_URL]
---

Query the sales table for yesterday's metrics.
Generate an executive summary with trends and anomalies.

Adding Capabilities with Tools

Out of the box, an agent can only read and write text. To give it access to the outside world - websites, databases, files, APIs - you connect tools.

PK-Agent uses the Model Context Protocol (MCP) standard, which means hundreds of pre-built tools already exist. You list them in your agent's settings:

mcpServers:
  fetch:
    command: uvx
    args: [mcp-server-fetch]

That single block gives your agent the ability to read any webpage. No code to write, no setup beyond adding those lines.

Built-in tools

PK-Agent also comes with built-in tools you can enable directly.

File access

tools:
  filesystem:
    - path: .
      permissions: [read, write, edit]

Shell commands

tools:
  bash:
    commands:
      - "rg -n \"TODO\" ."

Window capture

tools:
  captureWindow: true

Running Agents

From a file

pk-agent run my-agent.pk-agent

With an extra prompt

Append a question or instruction at run time:

pk-agent run my-agent.pk-agent "Focus on stories about robotics"

On a schedule

Add a schedule line to your agent file and it runs automatically:

schedule: "0 9 * * *"      # Every day at 9 AM
schedule: "*/30 * * * *"   # Every 30 minutes

As an HTTP server

Start a server and trigger agents over the network:

pk-agent serve

Then from any app, script, or automation tool:

curl -X POST http://localhost:12233/run -d '{"agent": "my-agent"}'

Composing Agents Together

Agents can call other agents. A "manager" agent can delegate tasks to specialized "worker" agents, each with their own instructions and tools.

---
model: anthropic:claude-sonnet-4-5
subagents:
  researcher:
    path: ./researcher.pk-agent
  writer:
    path: ./writer.pk-agent
---

Use the researcher to gather information about today's AI news,
then hand the results to the writer to create a blog post draft.

You can also reference agents with a shorthand - just wrap the name in double brackets:

Use [[researcher]] to find sources, then [[writer]] to draft.

PK-Agent will find the agent files automatically and wire everything up.

Reusable Skills

If you find yourself writing the same instructions across multiple agents, save them as a skill - a reusable block of instructions stored in a SKILL.md file.

.pk-agent/
  skills/
    summarizer/
      SKILL.md        <-- reusable instructions

Reference a skill in any agent with triple brackets:

Apply [[[summarizer]]] to the fetched content.

List all available skills:

pk-agent skills

All Commands

| Command | What it does | |---|---| | pk-agent run <file> | Run an agent | | pk-agent test <target> | Validate an agent file or URL (no execution) | | pk-agent config <subcommand> | Manage non-secret defaults (user and project scope) | | pk-agent serve | Start the HTTP server | | pk-agent auth login | Connect an AI provider | | pk-agent sessions | View past agent runs | | pk-agent agents | List agents in your project | | pk-agent skills | List available skills | | pk-agent models | Show supported AI models | | pk-agent add <source> | Import agents or skills from a URL or repo |

Platform Support

PK-Agent runs on Windows, macOS, and Linux.

It also works in Docker containers, GitHub Actions, and any CI/CD pipeline - anywhere Node.js runs.