[English](README.md) | [简体中文](README.zh-CN.md)
# PaddedCell
OpenClaw plugin for secure password management, safe command execution, and coordinated agent restart.
## Features
### 1. pass_mgr - Password Manager Binary (Go)
AES-256-GCM encryption, per-agent key-based encryption/decryption.
```bash
# Initialize
pass_mgr admin init [--key-path ]
# Get password
pass_mgr get [--username]
# Generate password (agent can use)
pass_mgr generate [--username ]
# Set password (human only)
pass_mgr set [--username ]
# Delete password
pass_mgr unset
# Rotate password
pass_mgr rotate
```
**Security Features:**
- Agents cannot execute `set` (detected via environment variables)
- All operations fail before initialization
- Admin password leak detection (monitors messages/tool calls)
### 2. pcexec - Safe Execution Tool (TypeScript)
Compatible with OpenClaw native exec interface, automatically handles `pass_mgr get` and sanitizes output.
```typescript
import { pcexec } from 'pcexec';
const result = await pcexec('echo $(pass_mgr get mypassword)', {
cwd: '/workspace',
timeout: 30000,
});
// Passwords in result.stdout will be replaced with ######
```
### 3. safe-restart - Safe Restart Module (TypeScript)
Provides agent state management and coordinated restart.
**Agent States:**
- `idle` - Idle
- `busy` - Processing messages
- `focus` - Focus mode (workflow)
- `freeze` - Frozen (not accepting new messages)
- `pre-freeze` - Preparing to freeze
- `pre-freeze-focus` - Preparing to freeze (focus mode)
**APIs:**
- `POST /query-restart` - Query restart readiness
- `POST /restart-result` - Report restart result
- `GET /status` - Get all statuses
**Slash Commands:**
```
/padded-cell-ctrl status
/padded-cell-ctrl enable pass-mgr|safe-restart
/padded-cell-ctrl disable pass-mgr|safe-restart
```
## Project Structure
```
PaddedCell/
├── pass_mgr/ # Go password manager binary
│ ├── src/
│ │ └── main.go
│ └── go.mod
├── pcexec/ # TypeScript safe execution tool
│ ├── src/
│ │ └── index.ts
│ ├── package.json
│ └── tsconfig.json
├── safe-restart/ # TypeScript safe restart module
│ ├── src/
│ │ ├── index.ts
│ │ ├── status-manager.ts
│ │ ├── api.ts
│ │ ├── safe-restart.ts
│ │ └── slash-commands.ts
│ ├── package.json
│ └── tsconfig.json
├── docs/ # Documentation
├── PROJECT_PLAN.md # Project plan
├── AGENT_TASKS.md # Task list
├── README.md # This file (English)
└── README.zh-CN.md # Chinese version
```
## Development
```bash
# Clone
git clone https://git.hangman-lab.top/nav/PaddedCell.git
cd PaddedCell
# Build pass_mgr (requires Go)
cd pass_mgr
go build -o pass_mgr src/main.go
# Build pcexec (requires Node.js)
cd ../pcexec
npm install
npm run build
# Build safe-restart (requires Node.js)
cd ../safe-restart
npm install
npm run build
```
## Branches
- `main` - Main branch
- `dev/zhi` - Development branch
## License
MIT