npm package: @harijitofficial/thinkingsilicon
Description: ThinkingSilicon – The enterprise-grade, model-agnostic agentic CLI. Like Claude Code, but works with any AI model.
Latest version: 0.3.0

<div align="center">

# ⚡ ThinkingSilicon

**The enterprise-grade, model-agnostic agentic CLI.**

Like Claude Code, but works with any AI model.

[![npm version](https://img.shields.io/npm/v/@harijitofficial/thinkingsilicon)](https://www.npmjs.com/package/@harijitofficial/thinkingsilicon)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-green)](https://nodejs.org)

</div>

---

## Why ThinkingSilicon?

- **Model-agnostic** — Claude, GPT-4o, Ollama, vLLM, OpenRouter, AWS Bedrock
- **Auto-detection** — Discovers local Ollama models automatically
- **Self-healing** — Watchdog agent detects and repairs failures
- **MCP-native** — First-class Model Context Protocol support
- **Enterprise-ready** — Audit logs, security hardening, hooks system
- **Skills system** — Create and share reusable agent skills
- **Sub-agents** — Delegate work to specialized agents with isolated sessions
- **Model failover** — Automatic failover chain with exponential backoff

---

## Quick Start

```bash
# Install globally
npm install -g @harijitofficial/thinkingsilicon

# Run setup wizard (detects providers, validates keys, generates config)
thinkingsilicon onboard

# Start chatting
thinkingsilicon
```

---

## Usage

```bash
# Interactive mode
thinkingsilicon

# One-shot query
thinkingsilicon --print "explain this error log"

# Use a specific model
thinkingsilicon --model ollama/llama3.3

# JSON output (great for scripts and pipelines)
thinkingsilicon --json --print "list all TODO comments"

# Resume a session
thinkingsilicon --session my-project
```

---

## Configuration

ThinkingSilicon uses [JSON5](https://json5.org) config files with layered resolution:

1. **Global**: `~/.thinkingsilicon/config.json5`
2. **Project**: `.thinkingsilicon/config.json5` (merged on top)
3. **Environment variables**: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`

```json5
// ~/.thinkingsilicon/config.json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-5",
        fallbacks: ["openai/gpt-4o", "ollama/llama3.3"]
      },
      thinking: "medium",       // off | minimal | low | medium | high | xhigh
      maxTurns: 50,
      tools: {
        allow: ["*"],
        deny: [],
        bashDefault: "ask"      // allow | ask | deny
      }
    }
  },
  gateway: { port: 19000, bind: "127.0.0.1" },
  cron: { enabled: true },
  logging: { redactSensitive: true }
}
```

See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the full reference.

---

## Models

ThinkingSilicon supports multiple providers out of the box:

| Provider | Models | Setup |
|----------|--------|-------|
| **Anthropic** | Claude Opus 4.5, Sonnet 4.5, Haiku 4.5, Opus 4, Sonnet 4 | `ANTHROPIC_API_KEY` |
| **OpenAI** | GPT-4o, GPT-4o-mini, o1, o3, o3-mini | `OPENAI_API_KEY` |
| **Ollama** | Any local model (llama3.3, mistral, codellama, ...) | Running on `localhost:11434` |
| **OpenAI-compatible** | vLLM, OpenRouter, LM Studio, text-gen-webui | Custom provider config |

```bash
# List all available models
thinkingsilicon models list

# Use a specific model for one query
thinkingsilicon --model openai/gpt-4o --print "summarize this file"

# Ollama auto-detection: just start Ollama and models appear
ollama run llama3.3
thinkingsilicon --model ollama/llama3.3
```

**Failover**: If the primary model fails (rate limit, billing, network), ThinkingSilicon automatically tries the next model in the fallback chain with exponential backoff.

---

## MCP (Model Context Protocol)

ThinkingSilicon has first-class MCP support for extending the agent's capabilities:

```bash
# Add from the built-in catalog
thinkingsilicon mcp add --from filesystem
thinkingsilicon mcp add --from github

# Add a custom server
thinkingsilicon mcp add --name my-api --transport http --url https://my-mcp.example.com/mcp

# Add a stdio server
thinkingsilicon mcp add --name local-fs --command npx --args -y @modelcontextprotocol/server-filesystem /workspace

# Manage servers
thinkingsilicon mcp list
thinkingsilicon mcp test              # verify connectivity
thinkingsilicon mcp tools             # list all exposed tools
thinkingsilicon mcp disable my-api    # disable without removing
thinkingsilicon mcp status            # live connectivity check
```

MCP tools appear as `mcp__<server>__<tool>` in the agent's tool registry and are discovered automatically on startup.

See [docs/MCP.md](docs/MCP.md) for the full integration guide.

---

## Skills

Skills are reusable agent behaviors defined as Markdown files with YAML frontmatter:

```bash
# List installed skills
thinkingsilicon skills list

# Create a new skill
thinkingsilicon skills create deploy-to-fly

# Learn a skill (agent researches, experiments, validates, publishes)
thinkingsilicon learn "how to deploy a Next.js app to Fly.io"

# Invoke a skill
thinkingsilicon skills run deploy-to-fly my-app

# In chat, use slash commands:
#   /deploy-to-fly my-app
```

Skills support:
- **Scopes**: project (`.thinkingsilicon/skills/`), user (`~/.thinkingsilicon/skills/`), learned
- **Tool restrictions**: Limit which tools the skill can use
- **Model override**: Use a specific model for a skill
- **Aliases**: Multiple slash-command triggers
- **Sub-agent mode**: Run in an isolated session

See [docs/SKILLS.md](docs/SKILLS.md) for the full guide.

---

## Sub-Agents

Create specialized agents in `.thinkingsilicon/agents/<name>.md`:

```markdown
---
name: code-reviewer
description: Reviews pull requests for quality, security, and style.
model: anthropic/claude-sonnet-4
thinking: low
maxTurns: 20
tools: [Read, Grep, Glob, Bash]
---

You are a code review agent. When invoked:
1. Read the changed files
2. Check for bugs, security issues, and style violations
3. Return a structured review
```

```bash
thinkingsilicon agents list
thinkingsilicon agents create my-agent
```

Built-in agents:
- **watchdog** — self-healing health monitor
- **security-auditor** — comprehensive security review

---

## Gateway Server

The gateway provides HTTP/WebSocket access to ThinkingSilicon:

```bash
# Start (loopback only by default)
thinkingsilicon gateway start

# Endpoints:
#   http://127.0.0.1:19000           Gateway API
#   http://127.0.0.1:19000/dashboard Web dashboard
#   http://127.0.0.1:19000/chat      WebChat UI

# Check status
thinkingsilicon gateway status

# Open dashboard in browser
thinkingsilicon dashboard
```

---

## Cron Scheduler

Schedule recurring agent tasks:

```bash
# Add a cron job
thinkingsilicon cron add \
  --name "daily-summary" \
  --cron "0 9 * * *" \
  --message "Summarize yesterday's git commits" \
  --model anthropic/claude-sonnet-4

# One-shot scheduled task
thinkingsilicon cron add --name "reminder" --at "20m" --message "Check build status"

# Repeating interval
thinkingsilicon cron add --name "health" --every "5m" --message "Run health check"

# Manage
thinkingsilicon cron list
thinkingsilicon cron run <jobId>      # run immediately
thinkingsilicon cron runs <jobId>     # view run history
thinkingsilicon cron remove <jobId>
```

---

## Self-Healing

Register the watchdog agent as a cron job for automatic health monitoring:

```bash
thinkingsilicon cron add \
  --name "watchdog" \
  --cron "*/5 * * * *" \
  --session isolated \
  --message "Run the watchdog health check and self-healing cycle." \
  --model anthropic/claude-sonnet-4 \
  --thinking low

thinkingsilicon gateway start  # gateway must be running
```

The watchdog:
1. Probes `thinkingsilicon health --json`
2. Detects: gateway down, disk critical, MCP disconnected, session overflow
3. Repairs each issue using safe commands
4. Escalates after 3 consecutive failures (no infinite loops)
5. Logs to `~/.thinkingsilicon/workspace/memory/YYYY-MM-DD.md`

---

## Security

ThinkingSilicon defaults to a hardened configuration:

| Control | Default |
|---------|---------|
| Gateway binding | `127.0.0.1` (loopback only) |
| Bash execution | `ask` (requires approval) |
| Tool deny list | Configurable (`deny` overrides `allow`) |
| Log redaction | API keys never appear in logs |
| Workspace containment | File ops restricted to workspace root |

```bash
# Run security audit
thinkingsilicon security audit

# Auto-fix safe issues (file permissions, etc.)
thinkingsilicon security audit --fix

# Full health check
thinkingsilicon health --json

# Diagnose configuration issues
thinkingsilicon doctor --fix
```

See [docs/SECURITY.md](docs/SECURITY.md) for the full security model.

---

## Project Instructions

Create a `.thinkingsilicon.md` file in your project root to give the agent context:

```markdown
# Project Instructions

## Project Overview
A Next.js e-commerce app with Stripe payments.

## Tech Stack
TypeScript, Next.js 14, Prisma, PostgreSQL, Stripe

## Conventions
- Use server components by default
- All API routes in app/api/
- Zod for validation

## Do's and Don'ts
- DO use the Prisma client from lib/db.ts
- DON'T modify migration files directly
```

The `thinkingsilicon onboard` wizard creates this template automatically.

---

## Shell Completions

```bash
# Bash
eval "$(thinkingsilicon completions bash)"    # add to ~/.bashrc

# Zsh
eval "$(thinkingsilicon completions zsh)"     # add to ~/.zshrc

# Fish
thinkingsilicon completions fish > ~/.config/fish/completions/thinkingsilicon.fish
```

---

## CLI Reference

```
thinkingsilicon                          Interactive chat
thinkingsilicon --print <msg>            One-shot query
thinkingsilicon --json --print <msg>     JSON output
thinkingsilicon --model <model>          Override model
thinkingsilicon --session <key>          Use session

thinkingsilicon chat                     Start chat session
thinkingsilicon learn <goal>             Self-study a skill
thinkingsilicon onboard                  Setup wizard

thinkingsilicon gateway start|stop|status
thinkingsilicon dashboard                Open web dashboard

thinkingsilicon cron add|list|run|remove|runs
thinkingsilicon sessions list|cleanup

thinkingsilicon mcp list|add|remove|enable|disable|test|tools|status|discover
thinkingsilicon models list
thinkingsilicon memory search|show|reindex

thinkingsilicon skills list|run|create|show
thinkingsilicon agents list|create

thinkingsilicon health [--json]          Health snapshot
thinkingsilicon doctor [--fix]           Diagnose issues
thinkingsilicon security audit [--fix]   Security audit

thinkingsilicon config get <key>
thinkingsilicon completions bash|zsh|fish
thinkingsilicon update [--check]
thinkingsilicon uninstall
```

---

## Architecture

```
src/
├── index.ts                 CLI entry point (Commander)
├── config/                  JSON5 config loading, Zod schemas
├── models/                  Provider abstraction + failover
│   ├── anthropic.ts         Claude (extended thinking)
│   ├── openai.ts            GPT-4o (streaming tool use)
│   ├── ollama.ts            Ollama + OpenAI-compatible
│   └── failover.ts          Registry + backoff chain
├── tools/                   Tool registry + permission layer
│   └── native/              Bash, Read, Write, Edit, Grep, Glob
├── agent/                   Core loop, sessions, memory, skills
├── mcp/                     MCP client (stdio + HTTP), registry
├── gateway/                 Express HTTP/WS server, cron, hooks
├── security/                Audit + auto-fix
└── cli/commands/            Command implementations
```

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full design.

---

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Make your changes and ensure `npm run build` passes
4. Submit a pull request

### Development

```bash
git clone https://github.com/harijitofficial/ThinkingSilicon.git
cd ThinkingSilicon
npm install
npm run build

# Run in dev mode
npx tsx src/index.ts

# Type check
npm run typecheck
```

---

## License

MIT — build something extraordinary.