You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jun 3, 2026. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+12-11Lines changed: 12 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,15 @@
1
-
# Plexir 🌌
1
+
# Plexir
2
2
3
3
**Plexir** is a modular, secure, and beautiful AI-powered terminal workspace. Designed for developers who live in the CLI, it combines multi-provider LLM orchestration, advanced agentic tools, and a secure, persistent Docker sandbox into a single keyboard-centric interface.
-**Multi-Provider Failover**: Seamlessly switch between Gemini, Groq, Cerebras, and OpenAI-compatible APIs. If one model hits a quota, Plexir automatically fails over to the next in your priority list.
15
15
-**Economics & Metrics**: Real-time **Token Tracking** and **Cost Estimation** in the sidebar. Set a session budget via `/config budget` to prevent runaway costs.
@@ -18,6 +18,7 @@
18
18
-**Persistent Memory Bank**: Semantic storage (`chromadb`) for long-term facts using `/memory save`.
19
19
-**Rolling Summarization**: Automatically condenses long histories.
20
20
-**Message Pinning**: `/session pin` ensures critical context is never lost.
21
+
-**Context Window Management**: Intelligent token counting and history pruning ensures conversations never exceed model limits, preventing failover loops.
21
22
-**Persistent Docker Sandbox**: Launch with `--sandbox` to give the AI its own persistent Linux "computer." All tools (file system, git, shell) are automatically redirected inside the container.
22
23
-**Deep MCP Integration**: Fully supports **Model Context Protocol (MCP)**, including dynamic discovery of tools, **Resources**, **Resource Templates**, and **Prompts** from MCP servers.
23
24
-**Smart Agent Capabilities**:
@@ -42,7 +43,7 @@
42
43
43
44
---
44
45
45
-
## 📦 Installation
46
+
## Installation
46
47
47
48
### Prerequisites
48
49
- Python 3.10 or higher.
@@ -61,7 +62,7 @@
61
62
62
63
---
63
64
64
-
## 🛠 Usage
65
+
## Usage
65
66
66
67
Start Plexir from any terminal:
67
68
```bash
@@ -90,7 +91,7 @@ plexir --sandbox
90
91
91
92
---
92
93
93
-
## ⚙️ Configuration
94
+
## Configuration
94
95
95
96
Plexir stores its configuration in `~/.plexir/config.json`. You can manage this file manually or using the in-app `/config` commands.
96
97
@@ -101,7 +102,7 @@ Example failover hierarchy:
101
102
102
103
---
103
104
104
-
## 📄 Documentation
105
+
## Documentation
105
106
106
107
Detailed guides are available in the `docs/` directory:
107
108
-[Getting Started](docs/getting_started.md)
@@ -113,14 +114,14 @@ Detailed guides are available in the `docs/` directory:
113
114
114
115
---
115
116
116
-
## 🤝 Contributing
117
+
## Contributing
117
118
118
119
Contributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) for more details.
119
120
120
-
## 🛡️ Security
121
+
## Security
121
122
122
123
If you discover a security vulnerability, please see our [Security Policy](SECURITY.md).
123
124
124
-
## ⚖️ License
125
+
## License
125
126
126
-
Plexir is released under the [MIT License](LICENSE).
127
+
Plexir is released under the [MIT License](LICENSE).
Copy file name to clipboardExpand all lines: docs/configuration.md
+22-1Lines changed: 22 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,6 +26,27 @@ Instead of plain text, you can use:
26
26
-`env:VARIABLE_NAME`: Read from environment variables.
27
27
-`keyring:username`: Read from the system keyring (service: `plexir`).
28
28
29
+
## Context Management
30
+
31
+
Plexir automatically manages the context window to prevent model errors when conversations get too long.
32
+
33
+
### Automatic Limits
34
+
Plexir comes with pre-configured token limits for popular models (e.g., 2M tokens for Gemini 1.5 Pro, 128k for GPT-4o). When the conversation history exceeds this limit, Plexir will:
35
+
1.**Preserve** the most recent messages.
36
+
2.**Preserve** system instructions.
37
+
3.**Summarize/Distill** the older parts of the conversation to save space while retaining context.
38
+
39
+
### Manual Configuration (`context_limit`)
40
+
You can override the default limit for any provider. This is useful for:
41
+
- Testing how models behave with shorter context.
42
+
- Forcing stricter limits on "Preview" models to save costs.
43
+
44
+
To set a strict 50,000 token limit on a provider:
45
+
```bash
46
+
/config set"Gemini Primary" context_limit 50000
47
+
```
48
+
*Set to `0` or `null` to use the model's default.*
49
+
29
50
## Failover & Retries
30
51
31
52
Plexir manages providers using a priority order defined in your config.
@@ -87,4 +108,4 @@ To prevent unexpected costs during long sessions, you can set a maximum dollar a
87
108
*Set to `0` to disable the limit.*
88
109
89
110
### View current usage
90
-
Usage metrics (Tokens and Estimated Cost) are always visible in the **System Status** sidebar.
111
+
Usage metrics (Tokens and Estimated Cost) are always visible in the **System Status** sidebar.
Copy file name to clipboardExpand all lines: docs/memory.md
+5-5Lines changed: 5 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
Plexir uses advanced techniques to manage long-running conversations, ensuring the model remains coherent even as the history grows.
4
4
5
-
## 🧠 Persistent Memory Bank (New in v1.7)
5
+
## Persistent Memory Bank (New in v1.7)
6
6
7
7
Plexir now includes a **Long-Term Memory** system powered by `chromadb`. This allows the agent to store and recall specific facts across different sessions.
8
8
@@ -20,15 +20,15 @@ You can prompt the agent to remember things directly:
20
20
Or ask it to recall:
21
21
> "Where did I say my keys were?"
22
22
23
-
## 🔄 Rolling Summarization
23
+
## Rolling Summarization
24
24
25
25
When a conversation history becomes too large (exceeding 40 messages), Plexir automatically triggers **Rolling Summarization**.
26
26
27
27
1.**How it works**: Plexir identifies older, unpinned messages and uses the primary LLM to condense them into a concise "BACKGROUND SUMMARY."
28
28
2.**Context Preservation**: This summary is injected at the start of the conversation, allowing the model to remember high-level decisions and context while clearing out detailed token-heavy noise.
29
29
3.**Automatic**: This happens in the background without user intervention.
30
30
31
-
## 📌 Message Pinning
31
+
## Message Pinning
32
32
33
33
You can manually protect critical messages from being summarized or pruned using **Context Pinning**.
34
34
@@ -44,6 +44,6 @@ Use the `/session pin` command followed by the message number (visible in the hi
44
44
/session unpin 5
45
45
```
46
46
47
-
## 🧠 Distillation (Failover)
47
+
## Distillation (Failover)
48
48
49
-
During a **Provider Failover** (e.g., Gemini Primary hitting a quota), Plexir uses a "Distillation" process to transfer only the most essential recent context to the backup provider. This ensures a smooth transition with minimal latency and token waste.
49
+
During a **Provider Failover** (e.g., Gemini Primary hitting a quota), Plexir uses a "Distillation" process to transfer only the most essential recent context to the backup provider. This ensures a smooth transition with minimal latency and token waste.
0 commit comments