Contributing

"The best way to predict the future is to implement it." — David Heinemeier Hansson

We welcome contributions to Pi Session Manager! Here's how to get started.

Prerequisites

Node.js 20+ with pnpm
Rust stable (via rustup)
Tauri CLI (cargo install tauri-cli)

Setup

Clone the repository

git clone https://github.com/Dwsy/pi-session-manager.git
cd pi-session-manager

Install dependencies

pnpm install

Start development

pnpm run tauri:dev

This launches both the Vite dev server (with HMR) and the Rust backend.

Project Structure

src/                          # Frontend (React + TypeScript)
  components/                 #   UI components (172 files, organized in subdirs)
  hooks/                      #   Custom React hooks (41)
  plugins/                    #   Search plugin system
  contexts/                   #   React contexts
  i18n/                       #   Internationalization (6 languages)
src-tauri/                    # Backend (Rust + Tauri 2)
  src/
    commands/                 #   Tauri IPC command handlers (17 modules)
    core/                     #   Pure business logic (scanner, parser, etc.)
    data/
      sqlite/                 #   SQLite data access layer
      search/                 #   Search engine (FTS5 + Tantivy)
    server/
      http/                   #   HTTP/Axum server
      ws.rs                   #   Standalone WebSocket (legacy)
    dispatch.rs               #   Shared command router
  tests/                      #   Integration tests
src-tauri-cli/                # CLI binary (standalone Rust)
website/                      # Documentation site (Next.js + Fumadocs)

Development Workflow

Code Style

TypeScript/React:

Functional components with hooks
TypeScript strict mode (strict: true, no any)
Import order: React → third-party → internal components → hooks → utils → types
Path aliases via @/* (e.g., @/components/App)

Rust:

cargo fmt for formatting (enforced in CI)
cargo clippy -D warnings for linting (enforced in CI)
Public functions return Result<T, String>
Document public functions with /// comments
Commands live in commands/, business logic in core/ and data/

Adding a New Command

When adding a new backend command, update these locations:

dispatch.rs — add a match arm in the command router
commands/mod.rs — export the new command module
lib.rs — re-export if needed for external consumers
WebSocket and HTTP automatically inherit from dispatch()

Example:

// In dispatch()
"my_command" => {
    let result = my_module::do_something(&state, &payload).await?;
    Ok(serde_json::to_value(result).unwrap())
}

Adding Frontend Components

// One component per file, PascalCase naming
function MyComponent({ prop1, prop2 }: MyComponentProps) {
  const { t } = useTranslation()
  const [state, setState] = useState<string>('')

  return <div>{t('my.key')}</div>
}

export default MyComponent

Testing

Rust Tests

cd src-tauri && cargo test
cd src-tauri && cargo test test_name -- --nocapture  # specific test with output
cd src-tauri && cargo test --test full_text_search_integration_test    # integration tests
cd src-tauri && cargo test --test migration_test    # migration tests

Code Quality Checks

cd src-tauri && cargo fmt --check
cd src-tauri && cargo clippy -- -D warnings
npx tsc --noEmit  # TypeScript type checking

Commit Convention

Use Conventional Commits:

feat: add session export to markdown
fix: resolve search not returning results
docs: update API documentation
refactor: simplify scanner logic
test: add unit tests for export module
chore: update dependencies

Extensions

psm-bridge (Pi Plugin)

Bridge Pi agent sessions to PSM with live sync, search, tags, and context recall.

Repository: Dwsy/psm-bridge

Install:

pi install npm:Dwsy/psm-bridge

Features:

Live mode: real-time session sync via WebSocket
Search: full-text search across indexed sessions
Tags: SQLite-backed session tagging
Context: recall and context from past sessions

Commands:

/psm-live on/off — Toggle live mode
/session_search — Full-text search
/state-set <tag> — Set session tag
/flow start/done/hold — Quick transitions

Local Development (submodule):

git clone --recurse-submodules https://github.com/Dwsy/pi-session-manager.git

Update submodule:

cd extensions/psm-bridge
# edit files...
git add . && git commit && git push

# Update parent repo
cd ../..
git add extensions/psm-bridge
git commit -m "Update psm-bridge"

Submitting Changes

Fork and branch

git checkout -b feature/my-feature

Make changes and test

cd src-tauri && cargo fmt && cargo clippy -- -D warnings
cd src-tauri && cargo test

Commit and push

git commit -m "feat: add my feature"
git push origin feature/my-feature

Open a Pull Request

Submit a PR against the main branch with a clear description of your changes.

All PRs must pass CI checks (rustfmt, clippy, build) before merging. The CI pipeline also builds the CLI binary as a sanity check.

Reporting Issues

When filing an issue, include:

OS and version (e.g., macOS 15.0, Windows 11)
App version (from Settings or package.json)
Steps to reproduce
Expected vs. actual behavior
Relevant logs or error messages

License

By contributing, you agree that your contributions will be licensed under the MIT License.

On this page