{"id":29709704,"url":"https://github.com/jefreesujit/cliffer","last_synced_at":"2026-05-19T04:11:43.978Z","repository":{"id":223096602,"uuid":"759301075","full_name":"Jefreesujit/cliffer","owner":"Jefreesujit","description":"AI powered CLI assistant with file system capabilities","archived":false,"fork":false,"pushed_at":"2025-07-11T19:51:57.000Z","size":102,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-11T20:35:28.812Z","etag":null,"topics":["agentic-ai","agents","ai","cli","filesystem","gemini","llm","tool","tool-calling"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/cliffer","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Jefreesujit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-02-18T07:47:08.000Z","updated_at":"2025-07-11T19:50:55.000Z","dependencies_parsed_at":"2024-10-31T03:41:28.215Z","dependency_job_id":"5fed989a-b8e1-49d5-9f4a-a7cec2028581","html_url":"https://github.com/Jefreesujit/cliffer","commit_stats":null,"previous_names":["jefreesujit/gemchat"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Jefreesujit/cliffer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jefreesujit%2Fcliffer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jefreesujit%2Fcliffer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jefreesujit%2Fcliffer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jefreesujit%2Fcliffer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Jefreesujit","download_url":"https://codeload.github.com/Jefreesujit/cliffer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Jefreesujit%2Fcliffer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266739598,"owners_count":23976621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agents","ai","cli","filesystem","gemini","llm","tool","tool-calling"],"created_at":"2025-07-23T20:10:49.464Z","updated_at":"2026-05-19T04:11:38.944Z","avatar_url":"https://github.com/Jefreesujit.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cliffer\n\nCliffer is a AI powered CLI assistant with file system capabilities. Built with TypeScript, it provides an interactive interface for communicating with the Gemini AI model and includes tools to perform file system operations.\n\n\u003e **Disclaimer**: This project is not affiliated with, endorsed by, or associated with Google or the Gemini AI team. It is an independent project created for development and testing purposes only.\n\n## Features\n\n- Interactive CLI-based chat interface\n- File system operations through natural language\n- Smart context handling\n- Error recovery and graceful degradation\n\n## Prerequisites\n\n- Node.js v18 or higher\n- npm v8 or higher\n- A Gemini API key (Get one for free at https://makersuite.google.com/app/apikey)\n\n## Installation \u0026 Setup\n\n1. Install Cliffer globally:\n```bash\nnpm install -g cliffer\n```\n\n2. Set up your Gemini API key using one of these methods:\n\n**Option 1: Shell configuration**\n```bash\n# Add to .bashrc or .zshrc\necho 'export GEMINI_API_KEY=your-api-key' \u003e\u003e ~/.bashrc\nsource ~/.zshrc\n```\n\n**Option 2: Direct export**\n```bash\nexport GEMINI_API_KEY=your-api-key\n```\n\n3. Run Cliffer with available options:\n   ```bash\n   cliffer [options]\n   ```\n\n   Alternatively, you can run without installing globally using npx:\n   ```bash\n   npx cliffer [options]\n   ```\n\n   **Available Options:**\n   ```bash\n   Options:\n     -V, --version            output version number\n     -k, --key \u003ckey\u003e         Gemini API key (can also use GEMINI_API_KEY env var)\n     -m, --model \u003cname\u003e      Gemini model to use (default: \"gemini-2.0-flash\")\n     -l, --langsmith-key \u003ckey\u003e  LangSmith API key for tracing (can also use LANGSMITH_API_KEY env var)\n     -t, --tracing           Enable tracing with LangSmith (default: false)\n     -h, --no-history        Disable chat history saving\n     --help                  display help for command\n   ```\n\n   **Examples:**\n   ```bash\n   # Using global installation\n   cliffer --key your-api-key\n   cliffer --model gemini-2.5-pro-exp-03-25\n\n   # Using npx\n   npx cliffer --key your-api-key\n   npx cliffer --tracing --langsmith-key your-langsmith-key\n   ```\n\n---\n\n## Cliffer File System MCP Server\n\nCliffer includes a File System MCP (Model Context Protocol) server that exposes file and folder operations as MCP tools. This allows any MCP-compatible client to connect and interact with your local file system securely through the Cliffer server.\n\n### Starting the MCP Server\n\nTo start the Cliffer MCP server (for file system operations):\n\n```bash\nnpx cliffer mcp\n# or, if installed globally\ncliffer mcp\n```\n\nThis will launch the server on standard input/output (stdio) and register all available file system tools (list, read, create, update, move, copy, delete, etc.).\n\n---\n\n### Connecting from Editors \u0026 Desktop Apps (VSCode, Cursor, Claude Desktop)\n\nMany modern editors and AI desktop apps now support the Model Context Protocol (MCP) for native tool integration. You can connect Cliffer's MCP server to these apps by providing a simple `mcp.json` configuration file.\n\n#### Example `mcp.json` for stdio (recommended for local Cliffer):\n\n```json\n{\n   \"mcpServers\": {\n      \"cliffer\": {\n         \"command\": \"npx\",\n         \"args\": [\"cliffer\", \"mcp\"],\n         \"env\": {}\n      }\n   }\n}\n```\n\n- Place this file where your editor/AI app expects MCP configs (see its documentation).\n- For VSCode (with MCP extension), open the MCP panel, click \"Add MCP Server\", and select or paste this config.\n- For Cursor/Claude Desktop, use their \"Connect MCP Tool\" or similar menu and provide this config.\n- You can use `npx cliffer mcp` in the `command` field if not installed globally.\n\n\u003e **Tip:** You can run multiple MCP servers for different projects or scopes by customizing the `cwd` or `args`.\n\n---\n\n### Available MCP Tools\n\n- listDirectory\n- readFile\n- createFile\n- updateFile\n- createFolder\n- deleteFolder\n- renameFolder\n- searchFiles\n- moveFile\n- copyFile\n\nEach tool is fully typed and described in the server for easy client discovery.\n\n### Connecting from a MCP Client\n\nTo connect to the Cliffer MCP server from an MCP-compatible client:\n\n1. **Ensure the server is running** (see above).\n2. **Configure your client** to connect via stdio, or use a compatible MCP client library that supports stdio transport.\n\n#### Example using @modelcontextprotocol/sdk (Node.js):\n\n```js\nimport { McpClient } from '@modelcontextprotocol/sdk/client/mcp.js';\nimport { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';\n\nconst transport = new StdioClientTransport({\n  command: 'npx',\n  args: ['cliffer', 'mcp'], // or ['node', 'dist/mcp-server.js'] if running locally\n});\nconst client = new McpClient(transport);\nawait client.connect();\n\n// List directory\nconst response = await client.callTool('listDirectory', { directory: '.' });\nconsole.log(response);\n```\n\nSee the [Model Context Protocol documentation](https://modelcontext.org/) for more details and client libraries.\n\n#### Example using CLI (if available):\n\nSome MCP clients provide a CLI interface to connect to an MCP server. Refer to your client's documentation for details.\n\n### Security Note\n\n- The Cliffer MCP server exposes your local file system via tools. **Run it only in trusted environments.**\n- Only the directory where the server is started (and its subdirectories) are accessible.\n\n---\n\n## Usage Examples\n\nCliffer supports various file system operations through natural language commands:\n\n1. **File Operations**\n   ```bash\n   # Read files\n   \u003e Show me the contents of config.json\n\n   # Create files\n   \u003e Create a new file called hello.js with a simple Hello World program\n\n   # Update files\n   \u003e Add error handling to the main function in index.js\n\n   # Get file/directory info\n   \u003e What's the size of the images directory?\n   ```\n\n2. **Folder Operations**\n   ```bash\n   # Create new folders\n   \u003e Create a folder called src/components\n\n   # Move folders\n   \u003e Move the utils folder into src\n\n   # Rename folders\n   \u003e Rename the helpers folder to utils\n\n   # Delete folders\n   \u003e Delete the temp directory\n   ```\n\n3. **Search Operations**\n   ```bash\n   # Find files by pattern\n   \u003e Find all JavaScript files in the src directory\n\n   # Search with recursive option\n   \u003e Search for files containing \"test\" in all directories\n   ```\n\n4. **File Management**\n   ```bash\n   # Copy files\n   \u003e Copy config.dev.json to config.prod.json\n\n   # Move files\n   \u003e Move old-readme.md to docs/archive.md\n\n   # List directory contents\n   \u003e Show me what's in the src folder\n   ```\n\n5. **Common Use Cases**\n   ```bash\n   # Setting up a new project structure\n   \u003e Create a new React project structure with components, styles, and utils folders\n\n   # Bulk file operations\n   \u003e Move all test files into the __tests__ directory\n\n   # Project cleanup\n   \u003e Delete all temporary files ending with .tmp\n   ```\n\n## Local Development\n\nTo set up the project for local development:\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/jefreesujit/cliffer.git\n   cd cliffer\n   ```\n\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Create a `.env` file:\n   ```\n   GEMINI_API_KEY=your-api-key\n   ```\n\n4. Start in development mode:\n   ```bash\n   npm run start\n   ```\n\n5. For debugging, use the DEBUG environment variable:\n   ```bash\n   DEBUG=true npm run start\n   ```\n\n## Contributing\n\nWe welcome contributions! Here's how you can help:\n\n### Reporting Issues\n\n- Use the GitHub issue tracker\n- Include steps to reproduce\n- Attach relevant logs or screenshots\n- Specify your environment details\n\n### Making Changes\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n### Code Style\n\n- Follow the existing TypeScript conventions\n- Use meaningful variable names\n- Add comments for complex logic\n- Keep functions focused and small\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n\n\nBefore contributing, please make sure to read and follow our Code of Conduct.\n\nThank you for your interest in contributing to Cliffer!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjefreesujit%2Fcliffer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjefreesujit%2Fcliffer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjefreesujit%2Fcliffer/lists"}