Experimental Research fork — APIs and behaviour may change without notice. Read disclaimer →

Workspace

Previous Next

The workspace (~/.picobot/workspace/) is picobot's working directory. It contains identity files, behavioral instructions, the knowledge base, skills, and task tracking. Everything in the workspace is git-tracked and auto-committed at session boundaries.

Template Files

picobot init creates these files. All are editable — changing them changes agent behavior immediately.

IDENTITY.md

Defines who the agent is and what it can do. Contains placeholders that are resolved at runtime:

  • {{timestamp}} — current date/time
  • {{runtime}} — OS, architecture, Python version
  • {{workspace_path}} — full path to workspace

This is the first thing in the system prompt. Edit it to change the agent's self-concept, capabilities description, or instructions about tool usage.

AGENTS.md

Behavioral instructions for the agent:

  • Review before creating (search for existing solutions first)
  • Plan multi-step work (use TODO.md for 3+ step tasks)
  • Sub-agent delegation patterns
  • General interaction guidelines

Think of this as the agent's standard operating procedures.

SOUL.md

Personality and values. Default is helpful, concise, and curious. Edit this to change the agent's communication style:

## Personality
- Direct and technical
- Prefer code examples over explanations
- Ask clarifying questions before starting complex work

## Values
- Correctness over speed
- Simplicity over cleverness

USER.md

Your profile — tells the agent about you. Fill this in for better personalization:

## Basic Information
- **Name**: Tim
- **Timezone**: UTC+10

## Preferences
- Communication Style: Technical
- Response Length: Concise
- Technical Level: Expert

## Work Context
- **Primary Role**: Developer
- **Main Projects**: picobot, other-project
- **Tools**: Python, TypeScript, VS Code

The more context you provide, the better the agent adapts.

TODO.md

Task tracking file. Injected into the system prompt every turn, so it survives context compression. Format:

## Refactor authentication
- [x] Extract token validation
- [ ] Add refresh token support
- [ ] Update tests

When all items in a section are checked off, the entire section should be removed. The todo skill (always loaded) teaches the agent this pattern.

HEARTBEAT.md

Periodic task file. Checked every 30 minutes by the default heartbeat cron job. Add tasks here for the agent to work on in the background:

## Active Tasks
- [ ] Check if any KB entries need updating
- [ ] Review recent journal entries for promotion opportunities

## Completed
<!-- Move done tasks here -->

If this file has no active tasks (only headers and comments), the heartbeat is skipped.

TOOLS.md

Reference documentation for all available tools. Loaded as part of the bootstrap files. Documents each tool's parameters and usage examples.

System Prompt Assembly

The system prompt is built in this order:

  1. IDENTITY.md with placeholder substitution
  2. Bootstrap files: AGENTS.md, SOUL.md, USER.md, TOOLS.md
  3. Knowledge base context (root README.md summary)
  4. TODO.md (only if it has active tasks)
  5. Always-on skills (full content)
  6. Available skills (summary list)

Sections are joined with --- separators. The total prompt is what the LLM sees before your message.

Git Tracking

The workspace has its own .git repository. WorkspaceGit auto-commits changes at session boundaries with a timestamp message. This means:

  • You can git log to see what changed and when
  • You can git diff to see uncommitted changes
  • You can git checkout to restore previous versions
  • picobot wipe destroys the .git and re-initializes

The agent can also use exec to run git commands directly.

Customization Tips

  • Change personality: Edit SOUL.md. The agent reads it every turn.
  • Add context about yourself: Fill in USER.md thoroughly.
  • Modify tool behavior: Edit TOOLS.md to add instructions about when/how to use specific tools.
  • Add periodic work: Edit HEARTBEAT.md with active tasks.
  • Create skills: Add skills/{name}/SKILL.md for domain-specific behavior.
  • Scope tool access: Use PathGuard config to restrict what the agent can access.

Changes take effect on the next agent invocation — no restart needed.

Token Budgets Configuration