Contributing

Clone, build, test, and submit pull requests.

Development Setup

Clone the repository and install dependencies:

bash

git clone https://github.com/blockrunai/franklin.git
cd franklin
npm install

Build

Compile TypeScript and bundle the CLI:

bash

npm run build

The compiled output goes to dist/. To test your local build globally:

bash

npm link

Test

Run the full test suite:

bash

npm test

To run a specific test file:

bash

npm test -- --grep "Smart Router"

Lint and Type Check

bash

# Lint
npm run lint

# Type check
npm run typecheck

# Run all checks (lint + typecheck + build)
npm run check

PR Guidelines

Open an issue first for significant changes. This lets us discuss the approach before you invest time writing code.
One PR per feature or fix. Keep changes focused and reviewable.
Add tests for new capabilities and bug fixes.
Follow existing patterns. Match the code style, naming conventions, and file structure of the surrounding code.
Write clear commit messages. Use conventional commits (e.g., feat:, fix:, docs:).

Before you start

For small fixes (typos, doc improvements), go ahead and open a PR directly. For anything that changes behavior — new tools, new flags, architecture changes — open an issue first so we can align on the approach.

Project Structure

text

src/
  agent/       Agent loop and orchestration
  tools/       Tool implementations
  router/      Smart Router and model selection
  wallet/      Payment and wallet management
  session/     Session persistence
  brain/       Long-term memory
  learnings/   Self-evolution rules
  cli/         CLI entry point and flag parsing
  plugins/     Plugin loader and SDK
  mcp/         MCP server integration
test/
  unit/        Unit tests
  integration/ Integration tests
  fixtures/    Test data and mocks

License

Franklin is licensed under Apache-2.0. By contributing, you agree that your contributions will be licensed under the same terms.