rait-09_obsidian-agent-client/CONTRIBUTING.md

Contributing to Agent Client Plugin

Thank you for your interest in contributing to the Agent Client plugin!

Before You Start

Please Open an Issue First

For significant changes, please open an issue before writing code:

• New features
• Architecture changes
• Adding or modifying external dependencies
• Implementing draft/experimental ACP specifications

This helps ensure alignment with the project direction and saves time for both contributors and maintainers.

You can submit a PR directly for:

• Obvious bug fixes (typos, crashes, etc.)
• Fixes for existing issues
• Documentation improvements

Project Scope

This plugin focuses on ACP client implementation + features that make ACP convenient to use in Obsidian.

In scope:

• ACP protocol implementation
• Note mentions (@[[note]] to pass note content to agents)
• Obsidian-specific UI integration

Out of scope:

• Features achievable via standard protocols like MCP (these should be provided as MCP servers for a consistent experience across all agents)
• Agent-specific features (these should be handled via agent-specific config files, e.g., .claude/ directory)

Development Setup

Prerequisites

• Node.js 18.x or later
• npm

Setup Steps

# Navigate to your vault's plugins directory
cd /path/to/your/vault/.obsidian/plugins

# Clone the repository as "agent-client"
# The directory name must match the id in manifest.json
git clone https://github.com/RAIT-09/obsidian-agent-client.git agent-client
cd agent-client

# Install dependencies
npm install

# Start development build (watch mode)
npm run dev

Testing in Obsidian

1. After cloning to .obsidian/plugins/agent-client, run npm run dev
2. Enable the plugin in Obsidian Settings → Community Plugins
3. Code changes trigger automatic rebuilds, but you need to reload the plugin (toggle it off/on in Community Plugins) to see changes

Available Commands

Command	Description
npm run dev	Development build (watch mode)
npm run build	Production build (includes TypeScript type check)
npm run lint	Run ESLint
npm run lint:fix	Run ESLint with auto-fix
npm run format	Format code with Prettier
npm run format:check	Check formatting (used in CI)

Code Style

Prettier Configuration

Setting	Value
Indentation	Tabs (width 4)
Semicolons	Yes
Quotes	Double
Trailing comma	All
Print width	80
End of line	LF

ESLint

We use eslint-plugin-obsidianmd for Obsidian-specific rules and typescript-eslint for TypeScript.

Obsidian Plugin Guidelines

1. No innerHTML/outerHTML — Use createEl, createDiv, createSpan
2. Don't detach leaves in onunload — This is an anti-pattern
3. Styles in CSS only — No JS style manipulation
4. Use Platform API — Don't use process.platform
5. Minimize any — Use proper types

File Naming Conventions

• Types: kebab-case.ts in types/
• ACP: kebab-case.ts in acp/
• Services: kebab-case.ts in services/
• Hooks: use*.ts in hooks/
• Components: PascalCase.tsx in ui/
• Utilities: kebab-case.ts in utils/

Branch Naming

{username}/{type}/{description}

Types:

• feature/ — New feature
• fix/ — Bug fix
• refactor/ — Refactoring
• docs/ — Documentation
• hotfix/ — Urgent fix

Examples:

• yourname/feature/add-export
• yourname/fix/message-rendering

Commit Messages

We recommend Conventional Commits style:

<type>: <description>

<optional body>

Types:

• feat: — New feature
• fix: — Bug fix
• refactor: — Refactoring
• docs: — Documentation
• chore: — Build/dependencies
• style: — Formatting (no functional changes)

Pull Request Process

Workflow

1. Create a branch from master
   • master is the stable branch, dev is for development
   • Feature PRs typically target dev, hotfixes target master
2. Make your changes and commit
3. Create a pull request
4. Ensure CI passes (lint, build)
5. Wait for review

PR Checklist

Before submitting, please verify:

• npm run lint passes
• npm run build passes
• Tested in Obsidian
• Existing functionality still works
• Documentation updated if needed

CI

Pull requests automatically run:

• ESLint (npx eslint src/)
• Build (npm run build)

Please ensure these pass locally before submitting.

Note: "Use sentence case for UI text" lint errors are acceptable for brand names and proper nouns (e.g., "Claude Code", "Gemini CLI").

Architecture Overview

src/
├── types/          # Pure type definitions (no logic, no dependencies)
├── acp/            # ACP protocol layer (SDK confined here)
├── services/       # Non-React business logic + pure functions
├── hooks/          # React custom hooks (useAgent facade + sub-hooks)
├── ui/             # React components (ChatPanel orchestrator)
└── utils/          # Shared utility functions

Architecture Principles

1. useAgent as facade — Composes useAgentSession + useAgentMessages. Single onSessionUpdate subscription.
2. Services have zero React imports — Pure functions and classes in services/
3. ACP isolation — All @agentclientprotocol/sdk imports confined to acp/
4. Types have zero deps — No obsidian, no SDK, no React in types/
5. Single event channel — All agent events flow through onSessionUpdate. No special callback paths.

For more details, see ARCHITECTURE.md.

ACP Notes

• Prioritize implementations that conform to the official (stable) ACP specification
• If implementing draft/experimental specs, please discuss in an issue first
• Implementations should work with official ACP-compatible agents (e.g., @agentclientprotocol/claude-agent-acp)

Questions?

Open an issue if you have any questions!