Basic Usage Guide for ORGN Studio

ORGN Studio organizes repository-backed development inside TDX sandboxes. Work flows through Projects, Tasks, Worktrees, and Sessions.

This guide explains how to work effectively inside a project, collaborate and manage execution.

Working Inside a Project

A project represents a deployed repository running inside a provisioned sandbox. Once deployed, the project includes:

• A cloned Git repository
• Indexed codebase for contextual reasoning
• Project-level environment variables
• Branch-based execution isolation

When you open a project, you are working against this controlled workspace.

Example: Backend API Repository

You import a backend service from GitHub and deploy it with a Standard runtime (4 CPU, 8GB RAM).

Once deployment completes:

• ORGN clones the repository
• The codebase is indexed
• The sandbox is provisioned
• You can immediately begin working

Tasks, worktrees, and sessions

Tasks live on the project backlog. Worktrees are isolated branches inside the project's shared TDX sandbox. Sessions are agent chats inside a worktree (/chat/:id). One task can have many worktrees; one worktree can have many sessions.

Work begins by creating or selecting a Task.

A task defines what needs to be accomplished.

When you start working on a task, ORGN creates a worktree — an isolated Git branch inside the project's TDX sandbox for that attempt.

Each worktree:

• Runs against a project-scoped branch
• Maintains its own execution history
• Can be reviewed independently
• Does not affect other worktrees

Example: Adding Rate Limiting

Task:

“Add rate limiting to the public API.”

When you begin, ORGN creates a worktree branch such as:

feature/add-rate-limiting-4821

All changes, reasoning, and commands executed during that work remain scoped to this worktree.

Sessions: Where Work Happens

Inside a worktree, work is recorded in Sessions.

A session captures:

• Your prompts
• Agent responses
• File edits
• Shell commands
• Diffs and changes
• Context references

Sessions persist. You can leave and return without losing history.

When to Start a New Session

Start a new session if:

• You want a clean reasoning history
• You’re switching from debugging to feature work
• You want to test an alternative implementation

Reference files

Inside a session chat, you can directly reference files from the codebase.

Typing @ in the chat lets you reference repository files and attach context directly into the conversation.

This keeps interactions precise and scoped. In addition to inline references, you can also attach broader context using the Context panel from the sidebar

This allows you to control exactly what the model sees and reasons over, whether it is a single file, a group of files, or structured project context.

Explorer and Code Navigation

The Explorer panel exposes the full repository file system as accessible to the sandbox.

You can:

• Browse directories
• Open files
• Inspect code
• Verify changes

The explorer reflects the exact state of the working branch.

Use Case: Debugging

If an integration test fails, you can:

1. Open the failing test file
2. Inspect related modules
3. Run commands in Terminal
4. Apply fixes within the same worktree

Terminal Execution

The Terminal is attached to the active sandbox.

You can:

• Install dependencies
• Run build scripts
• Execute tests
• Start services
• Inspect logs

Examples

Run tests:

pnpm test

Start a development server:

pnpm dev

Install a dependency:

pnpm add zod

All commands run within the worktree’s isolated environment.

Changes and Review

The Changes panel shows all file modifications made during the session or worktree.

You can:

• View diffs
• Inspect additions and deletions
• Review modified files
• Prepare commits

Example: Reviewing a Feature

After implementing rate limiting:

• Open the Changes panel
• Review modifications in middleware.ts
• Verify test updates
• Confirm no unintended file edits

Changes remain isolated until merged or pushed.

Typical Workflow Example

Scenario: Implementing API Integration Tests

1. Open project
2. Create task: “Add integration tests for chat route”
3. ORGN creates a worktree
4. Start session

Use:

locate existing test infrastructure

5. Open relevant files in Explorer

Run: pnpm test

6. Generate tests
7. Review Changes panel
8. Commit or prepare PR

All reasoning, file edits, and commands remain recorded.

Key Principles

ORGN maintains:

• Branch-isolated execution
• Persistent session history
• Indexed repository awareness
• Transparent diffs
• Controlled sandbox runtime

This structure allows you to:

• Experiment safely
• Work in parallel
• Review changes clearly
• Maintain clean development workflows