penguin-sdk

Penguin Harness SDK

@prismshadow/penguin-core is the TypeScript SDK this agent itself runs on. Use it to build your own AI apps:

• An Agent loads its state (prompts, tools, skills) from <root>/<project_id>/agents/<agent_id>/. Creating an Agent whose directory is empty initializes it with defaults.
• A Session is one conversation of an Agent inside a Workspace directory.
• session.run() executes one task and streams every step (thinking, text, tool calls) as OmniMessages.

To have an agent perform a task, use the run_subagent tool — the SDK is for building applications, not for invoking agents.

Before you start

If the user's message only invokes this skill (e.g. "use penguin-sdk skill") without a concrete app to build, ask the user what they want to build. But when the request names a concrete goal — even a single sentence like "build a RAG app that answers questions about these docs" — do not ask follow-up questions: build it end to end with the defaults in this skill (self-contained workspace project, project default model, BM25 retrieval, web UI styled per the web-design skill) and list the assumptions you made in your final reply.

Project location

Create the app in the current workspace directory by default (the CWD value from your Environment section), as a self-contained project — do not place it under <app_data_dir> (PenguinHarness's app data root) or depend on any path outside the project folder. When creating the app's agent, the data root defaults under the working directory (CWD) too: point createAgent({ root }) at a directory inside the project, resolved from the source file so it stays relative:

const agent = await createAgent({ root: path.join(import.meta.dirname, "penguin_data") });

With every reference relative to the project, the user can move or copy the folder anywhere and it still runs.

Keys and the data root — check before you build

The app's Penguin data root must live inside the CWD workspace — never ~/.penguin. Point createAgent({ root }) and every penguin config ... --root <dir> at a directory under the current working directory (e.g. ./penguin_data); the global ~/.penguin belongs to the person running Penguin and must never hold — or lend — the app's config or keys.