https://github.com/agustinsacco/tars
AI sidekick and personal assistant
https://github.com/agustinsacco/tars
agentic-workflows ai autonomous-agents gemini infrastructure mcp typescript
Last synced: 28 days ago
JSON representation
AI sidekick and personal assistant
- Host: GitHub
- URL: https://github.com/agustinsacco/tars
- Owner: agustinsacco
- Created: 2026-02-15T15:28:03.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-27T03:37:11.000Z (about 1 month ago)
- Last Synced: 2026-04-27T05:29:22.785Z (about 1 month ago)
- Topics: agentic-workflows, ai, autonomous-agents, gemini, infrastructure, mcp, typescript
- Language: TypeScript
- Homepage: https://tars.saccolabs.com
- Size: 7.78 MB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# Tars: Your Autonomous AI Assistant
[License: MIT](https://opensource.org/licenses/MIT) | [TypeScript](https://www.typescriptlang.org/) | [Powered by Gemini](https://deepmind.google/technologies/gemini/)
---
Tars is an autonomous, local-first AI assistant powered by Google's Gemini models. It provides a persistent, free alternative to subscription-based services by running directly on your machine. Tars maintains its own database of memories, tasks, and skills, allowing it to adapt to your workflow and retain context over time.
## Philosophy
Tars is designed for developers who need an assistant that integrates deeply with their local environment without the overhead of heavy containers or expensive cloud subscriptions.
- **Private**: All data, including memories and task history, is stored locally in your home directory.
- **Portable**: The entire "brain" can be exported and moved to a new machine seamlessly.
- **Extensible**: Tars can write its own tools and extensions to expand its capabilities.
- **Cost-Effective**: Utilizes the Gemini API (including the free tier) to handle complex reasoning tasks without local GPU requirements.
### Comparison
| Feature | Tars | Traditional Cloud Assistants |
| :---------- | :------------------------ | :------------------------------------------------ |
| **Cost** | Free (Gemini Tier) | Subscription / Token Usage Fees |
| **Runtime** | Native Node.js Process | Often Web-based or Heavy Local LLMs |
| **Latency** | Low (API Inference) | High (Local Inference) or Variable (Cloud Queues) |
| **Context** | Persistent Project Memory | Session-based / Limited Context Window |
| **Focus** | System & Code Execution | General Chat & Q&A |
---
## Key Features
- **Multi-Agent Orchestration**: Delegates specialized tasks (like coding or research) to sub-agents for better accuracy.
- **Native Gemini Core**: Integrated directly with the `@google/gemini-cli-core` library for high-speed, direct communication without subprocess overhead.
- **Autonomous Persistence**: A background "Heartbeat" service manages scheduled tasks and system health automatically.
- **Local Inference Support**: Tars can now be configured to use local models via **LlamaCpp** (or any OpenAI-compatible API) as an alternative to Gemini, providing 100% privacy and offline capability.
- **Context-Aware Memory**: Utilizes `GEMINI.md` files to maintain long-term awareness of project structures and decisions.
---
## Documentation
Full documentation is available at [tars.saccolabs.com](https://tars.saccolabs.com) or in the `site/` directory.
- **Website**: [tars.saccolabs.com](https://tars.saccolabs.com)
- **Development**: `npm run docs:dev`
- **Build**: `npm run docs:build`
- **Live Deployment**: `http://:5252`
## Installation and Setup
### Prerequisites
- **Node.js**: ≥ 22.0.2
### Installation
Tars is powered by the **Gemini CLI Core** library, which is automatically bundled during installation. No external CLI tools are required.
```bash
npm install -g @saccolabs/tars
```
### Initial Setup
Run the setup wizard to authorize Gemini and connect your Discord bot:
```bash
tars setup
```
---
## Usage
### Commands
- `tars start`: Launch the Tars supervisor.
- `tars restart`: Check for updates and restart the supervisor.
- `tars status`: View system health and brain statistics.
- `tars export`: Compress the brain and configuration for portability.
- `tars import `: Restore a brain with automatic path re-homing.
- `tars secret set `: Securely store platform credentials.
### Interaction
Tars communicates primarily through **Discord**. It supports file uploads, long-running task management, and complex multi-step instructions.
> **Discord**: `!tars Analyze the logs in /var/log/syslog and summarize any critical errors.`
---
## Architecture
Tars utilizes a Supervisor-Orchestrator model:
1. **Supervisor**: Manages persistent sessions and multi-channel communication.
2. **Channel Manager**: Orchestrates communication with Discord.
3. **Subagents**: Specialized expert agents invoked dynamically for specific technical domains.
4. **Heartbeat**: Cron-based engine for autonomous execution and cleanup.
5. **Extensions**: MCP servers that provide tool-level capabilities to the intelligence core.
---
## License
MIT Copyright Agustin Sacco